System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 8d56d871dcff40a7cb146b83e2213ef0c90ae407:


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 31 2e 30 2e 20 20  ersion 3.11.0.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d  e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72  ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56   options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c  C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20  d be done first 
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76  uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20  ent spurious.** 
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75  s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74  ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68  his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74  er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79   are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f   this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e  nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68  egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72  *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73  s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e  pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56  .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53  C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e  VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72  ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72  able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72  able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72  able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72  able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72  able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72  able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72  able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72  able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72  able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72  able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72  able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72  able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72  able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72  able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e  able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f  dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e  MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20  dif /* _MSVC_H_ 
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e  *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77  *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66  here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   in sqliteInt.h 
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57  al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65  vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a  le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54  15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57  is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f  ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64  ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e  efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56  EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20  xWorks.  Set up 
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79  things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a   for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b  #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70  s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d  thread.h>  /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63  algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ache */.#define 
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65  OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f  fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53  THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f  QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20  RECURSIVE_MUTEX 
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e  _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53  SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43  QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65  KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20  fine HAVE_UTIME 
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20  1.#else./* This 
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20  is not VxWorks. 
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 64 65 66 69 6e 65 20  WORKS 0.#define 
11f0: 48 41 56 45 5f 46 43 48 4f 57 4e 20 31 0a 23 64  HAVE_FCHOWN 1.#d
1200: 65 66 69 6e 65 20 48 41 56 45 5f 52 45 41 44 4c  efine HAVE_READL
1210: 49 4e 4b 20 31 0a 23 64 65 66 69 6e 65 20 48 41  INK 1.#define HA
1220: 56 45 5f 4c 53 54 41 54 20 31 0a 23 65 6e 64 69  VE_LSTAT 1.#endi
1230: 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 57 52  f /* defined(_WR
1240: 53 5f 4b 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a  S_KERNEL) */../*
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e  ************* En
1260: 64 20 6f 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a  d of vxworks.h *
1270: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1280: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1290: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a  ************/./*
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f  ************* Co
12b0: 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20 77  ntinuing where w
12c0: 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73 71  e left off in sq
12d0: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a  liteInt.h ******
12e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f  ************/../
12f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65 66 69  *.** These #defi
1300: 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c  nes should enabl
1310: 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75 70 70  e >2GB file supp
1320: 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69 66 20  ort on POSIX if 
1330: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
1340: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
1350: 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74 2e 20  em supports it. 
1360: 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63 6b 73   If the OS lacks
1370: 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65 20 73  .** large file s
1380: 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20 74 68  upport, or if th
1390: 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77 73 2c  e OS is windows,
13a0: 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20 62 65   these should be
13b0: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54   no-ops..**.** T
13c0: 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20 54 68  icket #2739:  Th
13d0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55  e _LARGEFILE_SOU
13e0: 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  RCE macro must a
13f0: 70 70 65 61 72 20 62 65 66 6f 72 65 20 61 6e 79  ppear before any
1400: 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e 63 6c  .** system #incl
1410: 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20 74 68  udes.  Hence, th
1420: 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65  is block of code
1430: 20 6d 75 73 74 20 62 65 20 74 68 65 20 76 65 72   must be the ver
1440: 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20  y first.** code 
1450: 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20 66 69  in all source fi
1460: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65  les..**.** Large
1470: 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 63 61   file support ca
1480: 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20 75 73  n be disabled us
1490: 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49 54 45  ing the -DSQLITE
14a0: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73 77 69  _DISABLE_LFS swi
14b0: 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f  tch.** on the co
14c0: 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c  mpiler command l
14d0: 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20 6e 65  ine.  This is ne
14e0: 63 65 73 73 61 72 79 20 69 66 20 79 6f 75 20 61  cessary if you a
14f0: 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20  re compiling.** 
1500: 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61 63 68  on a recent mach
1510: 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48 61 74  ine (ex: Red Hat
1520: 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20 77 61   7.2) but you wa
1530: 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74 6f 20  nt your code to 
1540: 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c  work.** on an ol
1550: 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65 78 3a  der machine (ex:
1560: 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e 20 20   Red Hat 6.0).  
1570: 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f  If you compile o
1580: 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a  n Red Hat 7.2.**
1590: 20 77 69 74 68 6f 75 74 20 74 68 69 73 20 6f 70   without this op
15a0: 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61  tion, LFS is ena
15b0: 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20 64 6f  ble.  But LFS do
15c0: 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 6e 20  es not exist in 
15d0: 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e  the kernel.** in
15e0: 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20 73 6f   Red Hat 6.0, so
15f0: 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27 74 20   the code won't 
1600: 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f  work.  Hence, fo
1610: 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61 72 79  r maximum binary
1620: 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74 79 20  .** portability 
1630: 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20  you should omit 
1640: 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  LFS..**.** The p
1650: 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1660: 68 20 77 61 73 20 77 72 69 74 74 65 6e 20 69 6e  h was written in
1670: 20 32 30 30 35 2e 20 20 28 54 68 69 73 20 70 61   2005.  (This pa
1680: 72 61 67 72 61 70 68 20 69 73 20 77 72 69 74 74  ragraph is writt
1690: 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31  en.** on 2008-11
16a0: 2d 32 38 2e 29 20 54 68 65 73 65 20 64 61 79 73  -28.) These days
16b0: 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e  , all Linux kern
16c0: 65 6c 73 20 73 75 70 70 6f 72 74 20 6c 61 72 67  els support larg
16d0: 65 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79  e files, so.** y
16e0: 6f 75 20 73 68 6f 75 6c 64 20 70 72 6f 62 61 62  ou should probab
16f0: 6c 79 20 6c 65 61 76 65 20 4c 46 53 20 65 6e 61  ly leave LFS ena
1700: 62 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d 65 20  bled.  But some 
1710: 65 6d 62 65 64 64 65 64 20 70 6c 61 74 66 6f 72  embedded platfor
1720: 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b  ms might.** lack
1730: 20 4c 46 53 20 69 6e 20 77 68 69 63 68 20 63 61   LFS in which ca
1740: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 44 49  se the SQLITE_DI
1750: 53 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20  SABLE_LFS macro 
1760: 6d 69 67 68 74 20 73 74 69 6c 6c 20 62 65 20 75  might still be u
1770: 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d  seful..**.** Sim
1780: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72  ilar is true for
1790: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20   Mac OS X.  LFS 
17a0: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65  is only supporte
17b0: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20  d on Mac OS X 9 
17c0: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69  and later..*/.#i
17d0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53  fndef SQLITE_DIS
17e0: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e  ABLE_LFS.# defin
17f0: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20  e _LARGE_FILE   
1800: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f      1.# ifndef _
1810: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
1820: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c  .#   define _FIL
1830: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34  E_OFFSET_BITS 64
1840: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e  .# endif.# defin
1850: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55  e _LARGEFILE_SOU
1860: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  RCE 1.#endif../*
1870: 20 57 68 61 74 20 76 65 72 73 69 6f 6e 20 6f 66   What version of
1880: 20 47 43 43 20 69 73 20 62 65 69 6e 67 20 75 73   GCC is being us
1890: 65 64 2e 20 20 30 20 6d 65 61 6e 73 20 47 43 43  ed.  0 means GCC
18a0: 20 69 73 20 6e 6f 74 20 62 65 69 6e 67 20 75 73   is not being us
18b0: 65 64 20 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47  ed */.#ifdef __G
18c0: 4e 55 43 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47  NUC__.# define G
18d0: 43 43 5f 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e  CC_VERSION (__GN
18e0: 55 43 5f 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47  UC__*1000000+__G
18f0: 4e 55 43 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30  NUC_MINOR__*1000
1900: 2b 5f 5f 47 4e 55 43 5f 50 41 54 43 48 4c 45 56  +__GNUC_PATCHLEV
1910: 45 4c 5f 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65  EL__).#else.# de
1920: 66 69 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e  fine GCC_VERSION
1930: 20 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65   0.#endif../* Ne
1940: 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 73  eded for various
1950: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20   definitions... 
1960: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
1970: 5f 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65 66  _GNUC__) && !def
1980: 69 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45  ined(_GNU_SOURCE
1990: 29 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f  ).# define _GNU_
19a0: 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23  SOURCE.#endif..#
19b0: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65  if defined(__Ope
19c0: 6e 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66 69  nBSD__) && !defi
19d0: 6e 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45 29  ned(_BSD_SOURCE)
19e0: 0a 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f 53  .# define _BSD_S
19f0: 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a  OURCE.#endif../*
1a00: 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63  .** For MinGW, c
1a10: 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 77  heck to see if w
1a20: 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74 68  e can include th
1a30: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 63 6f  e header file co
1a40: 6e 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20  ntaining its.** 
1a50: 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74  version informat
1a60: 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72  ion, among other
1a70: 20 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c   things.  Normal
1a80: 6c 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e 61  ly, this interna
1a90: 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65  l MinGW.** heade
1aa0: 72 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e  r file would [on
1ab0: 6c 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64 20  ly] be included 
1ac0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1ad0: 20 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65 61   other MinGW hea
1ae0: 64 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f  der.** files; ho
1af0: 77 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74 61  wever, the conta
1b00: 69 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e 66  ined version inf
1b10: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20  ormation is now 
1b20: 72 65 71 75 69 72 65 64 20 62 79 20 74 68 69 73  required by this
1b30: 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20  .** header file 
1b40: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62  to work around b
1b50: 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c  inary compatibil
1b60: 69 74 79 20 69 73 73 75 65 73 20 28 73 65 65 20  ity issues (see 
1b70: 62 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68  below) and.** th
1b80: 69 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b  is is the only k
1b90: 6e 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c 69  nown way to reli
1ba0: 61 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e 20  ably obtain it. 
1bb0: 20 54 68 69 73 20 65 6e 74 69 72 65 20 23 69 66   This entire #if
1bc0: 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20   block.** would 
1bd0: 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e  be completely un
1be0: 6e 65 63 65 73 73 61 72 79 20 69 66 20 74 68 65  necessary if the
1bf0: 72 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65 72  re was any other
1c00: 20 77 61 79 20 6f 66 20 64 65 74 65 63 74 69 6e   way of detectin
1c10: 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20 74  g.** MinGW via t
1c20: 68 65 69 72 20 70 72 65 70 72 6f 63 65 73 73 6f  heir preprocesso
1c30: 72 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79 20  r (e.g. if they 
1c40: 63 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69 72  customized their
1c50: 20 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a   GCC to define.*
1c60: 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65  * some MinGW-spe
1c70: 63 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20 20  cific macros).  
1c80: 57 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66  When compiling f
1c90: 6f 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65 72  or MinGW, either
1ca0: 20 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49   the.** _HAVE_MI
1cb0: 4e 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f  NGW_H or _HAVE__
1cc0: 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74 68  MINGW_H (note th
1cd0: 65 20 65 78 74 72 61 20 75 6e 64 65 72 73 63 6f  e extra undersco
1ce0: 72 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20 62  re) macro must b
1cf0: 65 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74  e.** defined; ot
1d00: 68 65 72 77 69 73 65 2c 20 64 65 74 65 63 74 69  herwise, detecti
1d10: 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73  on of conditions
1d20: 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69 6e   specific to Min
1d30: 47 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69  GW will be.** di
1d40: 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64  sabled..*/.#if d
1d50: 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e  efined(_HAVE_MIN
1d60: 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20  GW_H).# include 
1d70: 22 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20  "mingw.h".#elif 
1d80: 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d  defined(_HAVE__M
1d90: 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64  INGW_H).# includ
1da0: 65 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e  e "_mingw.h".#en
1db0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d  dif../*.** For M
1dc0: 69 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e 78  inGW version 4.x
1dd0: 20 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20 63   (and higher), c
1de0: 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 74  heck to see if t
1df0: 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49  he _USE_32BIT_TI
1e00: 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69  ME_T.** define i
1e10: 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d 61  s required to ma
1e20: 69 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63 6f  intain binary co
1e30: 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
1e40: 20 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69 6d   the MSVC runtim
1e50: 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e 20  e.** library in 
1e60: 75 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57 69  use (e.g. for Wi
1e70: 6e 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69  ndows XP)..*/.#i
1e80: 66 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f  f !defined(_USE_
1e90: 33 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26  32BIT_TIME_T) &&
1ea0: 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 36   !defined(_USE_6
1eb0: 34 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20  4BIT_TIME_T) && 
1ec0: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 57  \.    defined(_W
1ed0: 49 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e 65  IN32) && !define
1ee0: 64 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a 20  d(_WIN64) && \. 
1ef0: 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e     defined(__MIN
1f00: 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e  GW_MAJOR_VERSION
1f10: 29 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a  ) && __MINGW_MAJ
1f20: 4f 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20  OR_VERSION >= 4 
1f30: 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64  && \.    defined
1f40: 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64  (__MSVCRT__).# d
1f50: 65 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49 54  efine _USE_32BIT
1f60: 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a  _TIME_T.#endif..
1f70: 2f 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53 51  /* The public SQ
1f80: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
1f90: 20 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45   The _FILE_OFFSE
1fa0: 54 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75 73  T_BITS macro mus
1fb0: 74 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72 73  t appear.** firs
1fc0: 74 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c  t in QNX.  Also,
1fd0: 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f   the _USE_32BIT_
1fe0: 54 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73  TIME_T macro mus
1ff0: 74 20 61 70 70 65 61 72 20 66 69 72 73 74 20 66  t appear first f
2000: 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a  or.** MinGW..*/.
2010: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
2020: 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e  Include sqlite3.
2030: 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  h in the middle 
2040: 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  of sqliteInt.h *
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2060: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
2070: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
2080: 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e3.h ***********
2090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
20b0: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
20c0: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
20d0: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
20e0: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
20f0: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
2100: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
2110: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
2120: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
2130: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
2140: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
2150: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
2160: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
2170: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
2180: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
2190: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
21a0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
21b0: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
21c0: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
21d0: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
21e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2200: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2220: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
2230: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
2240: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
2250: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
2260: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
2270: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
2280: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
2290: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
22a0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
22b0: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
22c0: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
22d0: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
22e0: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
22f0: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
2300: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
2310: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
2320: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
2330: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
2340: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
2350: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
2360: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
2370: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
2380: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
2390: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
23a0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
23b0: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
23c0: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
23d0: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
23e0: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
23f0: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
2400: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
2410: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
2420: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
2430: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
2440: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
2450: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
2460: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
2470: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
2480: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
2490: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
24a0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
24b0: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
24c0: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
24d0: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
24e0: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
24f0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
2500: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
2510: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
2520: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
2530: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
2540: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
2550: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
2560: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
2570: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
2580: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
2590: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
25a0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
25b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
25c0: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
25d0: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
25e0: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
25f0: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
2600: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
2610: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
2620: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
2630: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
2640: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
2650: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
2660: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
2670: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
2680: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
2690: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
26a0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
26b0: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
26c0: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
26d0: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
26e0: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
26f0: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
2700: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
2710: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
2720: 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e  .*/.#if 0.extern
2730: 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a   "C" {.#endif...
2740: 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 74 68  /*.** Provide th
2750: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
2760: 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 66 65  rride linkage fe
2770: 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 69 6e  atures of the in
2780: 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e  terface..*/.#ifn
2790: 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52  def SQLITE_EXTER
27a0: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  N.# define SQLIT
27b0: 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a  E_EXTERN extern.
27c0: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
27d0: 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69  QLITE_API.# defi
27e0: 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65  ne SQLITE_API.#e
27f0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
2800: 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 66 69  ITE_CDECL.# defi
2810: 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a  ne SQLITE_CDECL.
2820: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
2830: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20  QLITE_STDCALL.# 
2840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2850: 44 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a  DCALL.#endif../*
2860: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
2870: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
2880: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
2890: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
28a0: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
28b0: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
28c0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
28d0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
28e0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
28f0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
2900: 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63  recated interfac
2910: 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75  es - they are su
2920: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
2930: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
2940: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70  bility only.  Ap
2950: 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72  plication writer
2960: 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72  s should be awar
2970: 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69  e that.** experi
2980: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
2990: 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f  s are subject to
29a0: 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74   change in point
29b0: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
29c0: 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73   These macros us
29d0: 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f  ed to resolve to
29e0: 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f   various kinds o
29f0: 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63  f compiler magic
2a00: 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67   that.** would g
2a10: 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20  enerate warning 
2a20: 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68  messages when th
2a30: 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42  ey were used.  B
2a40: 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69  ut that.** compi
2a50: 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20  ler magic ended 
2a60: 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75  up generating su
2a70: 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62  ch a flurry of b
2a80: 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68  ug reports.** th
2a90: 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e  at we have taken
2aa0: 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20   it all out and 
2ab0: 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69  gone back to usi
2ac0: 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f  ng simple.** noo
2ad0: 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65  p macros..*/.#de
2ae0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52  fine SQLITE_DEPR
2af0: 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53  ECATED.#define S
2b00: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
2b10: 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65  AL../*.** Ensure
2b20: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77   these symbols w
2b30: 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20  ere not defined 
2b40: 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73  by some previous
2b50: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f   header file..*/
2b60: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
2b70: 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53  ERSION.# undef S
2b80: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65  QLITE_VERSION.#e
2b90: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49  ndif.#ifdef SQLI
2ba0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
2bb0: 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  R.# undef SQLITE
2bc0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
2bd0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2be0: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
2bf0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
2c00: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a  sion Numbers.**.
2c10: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
2c20: 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70  _VERSION] C prep
2c30: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69  rocessor macro i
2c40: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20  n the sqlite3.h 
2c50: 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61  header.** evalua
2c60: 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20  tes to a string 
2c70: 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20  literal that is 
2c80: 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69  the SQLite versi
2c90: 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72  on in the.** for
2ca0: 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72  mat "X.Y.Z" wher
2cb0: 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72  e X is the major
2cc0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
2cd0: 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a  (always 3 for.**
2ce0: 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20   SQLite3) and Y 
2cf0: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
2d00: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
2d10: 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65  Z is the release
2d20: 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28   number.)^.** ^(
2d30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  The [SQLITE_VERS
2d40: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72  ION_NUMBER] C pr
2d50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
2d60: 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20   resolves to an 
2d70: 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20  integer.** with 
2d80: 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30  the value (X*100
2d90: 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20  0000 + Y*1000 + 
2da0: 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61  Z) where X, Y, a
2db0: 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d  nd Z are the sam
2dc0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65  e.** numbers use
2dd0: 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52  d in [SQLITE_VER
2de0: 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20  SION].)^.** The 
2df0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
2e00: 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69  UMBER for any gi
2e10: 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ven release of S
2e20: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a  QLite will also.
2e30: 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ** be larger tha
2e40: 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72  n the release fr
2e50: 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64  om which it is d
2e60: 65 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20  erived.  Either 
2e70: 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c  Y will.** be hel
2e80: 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a  d constant and Z
2e90: 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65   will be increme
2ea0: 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77  nted or else Y w
2eb0: 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74  ill be increment
2ec0: 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c  ed.** and Z will
2ed0: 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72   be reset to zer
2ee0: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76  o..**.** Since v
2ef0: 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53  ersion 3.6.18, S
2f00: 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
2f10: 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65  e has been store
2f20: 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68  d in the.** <a h
2f30: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e  ref="http://www.
2f40: 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22  fossil-scm.org/"
2f50: 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72  >Fossil configur
2f60: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
2f70: 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20  .** system</a>. 
2f80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
2f90: 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61  RCE_ID macro eva
2fa0: 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73  luates to.** a s
2fb0: 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e  tring which iden
2fc0: 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75  tifies a particu
2fd0: 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20  lar check-in of 
2fe0: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e  SQLite.** within
2ff0: 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69   its configurati
3000: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79  on management sy
3010: 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49  stem.  ^The SQLI
3020: 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20  TE_SOURCE_ID.** 
3030: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20  string contains 
3040: 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d  the date and tim
3050: 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69  e of the check-i
3060: 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53  n (UTC) and an S
3070: 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74  HA1.** hash of t
3080: 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65  he entire source
3090: 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   tree..**.** See
30a0: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a  libversion()],.*
30c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  * [sqlite3_libve
30d0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c  rsion_number()],
30e0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65   [sqlite3_source
30f0: 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  id()],.** [sqlit
3100: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
3110: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
3120: 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  id()]..*/.#defin
3130: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
3140: 20 20 20 20 20 20 20 20 22 33 2e 31 31 2e 30 22          "3.11.0"
3150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3160: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33  VERSION_NUMBER 3
3170: 30 31 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  011000.#define S
3180: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20  QLITE_SOURCE_ID 
3190: 20 20 20 20 20 22 32 30 31 36 2d 30 32 2d 31 32       "2016-02-12
31a0: 20 31 38 3a 34 38 3a 30 39 20 61 30 34 39 66 62   18:48:09 a049fb
31b0: 62 64 65 35 64 61 32 65 34 33 64 34 31 61 61 38  bde5da2e43d41aa8
31c0: 63 32 62 34 31 66 39 65 62 32 31 35 30 37 61 63  c2b41f9eb21507ac
31d0: 37 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  76"../*.** CAPI3
31e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
31f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
3200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
3210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
3220: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  on, sqlite3_sour
3230: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
3240: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
3250: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
3260: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
3270: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
3280: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
3290: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
32a0: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
32b0: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
32c0: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
32d0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
32e0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
32f0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
3300: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
3310: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
3320: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
3330: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
3340: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
3350: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
3360: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
3370: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
3380: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
3390: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
33a0: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
33b0: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
33c0: 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  s ensure that th
33d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
33e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
33f0: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
3400: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
3410: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
3420: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
3430: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
3440: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
3450: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
3460: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
3470: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
3480: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
3490: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
34a0: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
34b0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
34c0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
34d0: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
34e0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
34f0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
3500: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
3510: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
3520: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
3530: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
3540: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
3550: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
3560: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
3570: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
3580: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
3590: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
35a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
35b0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
35c0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
35d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
35e0: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
35f0: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
3600: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
3610: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
3620: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
3630: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
3640: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
3650: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
3660: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
3670: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
3680: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
3690: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
36a0: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
36b0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
36c0: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
36d0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
36e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
36f0: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
3700: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
3710: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
3720: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
3730: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
3740: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
3750: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
3760: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3770: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
3780: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
3790: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
37a0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
37b0: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
37c0: 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49  version[] = SQLI
37d0: 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49  TE_VERSION;.SQLI
37e0: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
37f0: 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
3800: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
3810: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
3820: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
3830: 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
3840: 4c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  L sqlite3_source
3850: 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  id(void);.SQLITE
3860: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
3870: 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
3880: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
3890: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
38a0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
38b0: 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69  me Library Compi
38c0: 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44  lation Options D
38d0: 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a  iagnostics.**.**
38e0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
38f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
3900: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
3910: 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69  rns 0 or 1 .** i
3920: 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65  ndicating whethe
3930: 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  r the specified 
3940: 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e  option was defin
3950: 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c  ed at .** compil
3960: 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51  e time.  ^The SQ
3970: 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79  LITE_ prefix may
3980: 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   be omitted from
3990: 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20   the .** option 
39a0: 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73  name passed to s
39b0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
39c0: 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a  tion_used().  .*
39d0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
39e0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
39f0: 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  get() function a
3a00: 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a  llows iterating.
3a10: 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74  ** over the list
3a20: 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74   of options that
3a30: 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74   were defined at
3a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79   compile time by
3a50: 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68  .** returning th
3a60: 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74  e N-th compile t
3a70: 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e  ime option strin
3a80: 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74  g.  ^If N is out
3a90: 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71   of range,.** sq
3aa0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
3ab0: 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e  ion_get() return
3ac0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3ad0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
3ae0: 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d  .** prefix is om
3af0: 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73  itted from any s
3b00: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3b10: 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  by .** sqlite3_c
3b20: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
3b30: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f  ()..**.** ^Suppo
3b40: 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e  rt for the diagn
3b50: 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20  ostic functions 
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
3b70: 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20  ption_used().** 
3b80: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
3b90: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
3ba0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62  may be omitted b
3bb0: 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65  y specifying the
3bc0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   .** [SQLITE_OMI
3bd0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
3be0: 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74  DIAGS] option at
3bf0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a   compile time..*
3c00: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53  *.** See also: S
3c10: 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71  QL functions [sq
3c20: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
3c30: 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  on_used()] and.*
3c40: 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  * [sqlite_compil
3c50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61  eoption_get()] a
3c60: 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f  nd the [compile_
3c70: 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e  options pragma].
3c80: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
3c90: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
3ca0: 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49  PTION_DIAGS.SQLI
3cb0: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
3cc0: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
3cd0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
3ce0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
3cf0: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49  *zOptName);.SQLI
3d00: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
3d10: 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
3d20: 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  L sqlite3_compil
3d30: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20  eoption_get(int 
3d40: 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  N);.#endif../*.*
3d50: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
3d60: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
3d70: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
3d80: 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  safe.**.** ^The 
3d90: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
3da0: 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  fe() function re
3db0: 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e  turns zero if an
3dc0: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c  d only if.** SQL
3dd0: 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ite was compiled
3de0: 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63   with mutexing c
3df0: 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20  ode omitted due 
3e00: 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  to the.** [SQLIT
3e10: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f  E_THREADSAFE] co
3e20: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
3e30: 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30  n being set to 0
3e40: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  ..**.** SQLite c
3e50: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
3e60: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
3e70: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
3e80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
3e90: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
3ea0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
3eb0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
3ec0: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
3ed0: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
3ee0: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
3ef0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
3f00: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
3f10: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
3f20: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
3f30: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
3f40: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
3f50: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
3f60: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
3f70: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
3f80: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
3f90: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
3fa0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
3fb0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
3fc0: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
3fd0: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
3fe0: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
3ff0: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
4000: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
4010: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
4020: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
4030: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
4040: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
4050: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nabled..** ^The 
4060: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
4070: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
4080: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
4090: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
40a0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
40b0: 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  by an applicatio
40c0: 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  n to make sure t
40d0: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
40e0: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
40f0: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
4100: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
4110: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
4120: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
4130: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
4140: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
4150: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  o..**.** This in
4160: 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
4170: 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  orts on the comp
4180: 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73  ile-time mutex s
4190: 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65  etting.** of the
41a0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
41b0: 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53  AFE] flag.  If S
41c0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
41d0: 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  d with.** SQLITE
41e0: 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72  _THREADSAFE=1 or
41f0: 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73   =2 then mutexes
4200: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
4210: 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63  default but.** c
4220: 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70  an be fully or p
4230: 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65  artially disable
4240: 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74  d using a call t
4250: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
4260: 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65  g()].** with the
4270: 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43   verbs [SQLITE_C
4280: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
4290: 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  AD], [SQLITE_CON
42a0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
42b0: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
42c0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
42d0: 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72  D].  ^(The retur
42e0: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a  n value of the.*
42f0: 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  * sqlite3_thread
4300: 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  safe() function 
4310: 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63  shows only the c
4320: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74  ompile-time sett
4330: 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64  ing of.** thread
4340: 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79   safety, not any
4350: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
4360: 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  s to that settin
4370: 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c  g made by.** sql
4380: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49  ite3_config(). I
4390: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
43a0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
43b0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72  from sqlite3_thr
43c0: 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20  eadsafe().** is 
43d0: 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c  unchanged by cal
43e0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
43f0: 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  nfig().)^.**.** 
4400: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
4410: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
4420: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
4430: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
4440: 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
4450: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
4460: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65  ALL sqlite3_thre
4470: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
4480: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
4490: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
44a0: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
44b0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
44c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
44d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
44e0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
44f0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
4500: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
4510: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
4520: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
4530: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
4540: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
4550: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
4560: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
4570: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
4580: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
4590: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
45a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
45b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
45c0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
45d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
45e0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
45f0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
4600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
4610: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
4620: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
4630: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
4640: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
4650: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
4660: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
4670: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
4680: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
4690: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
46a0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
46b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
46c0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
46d0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
46e0: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
46f0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
4700: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
4710: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
4720: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
4730: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
4740: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
4750: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
4760: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
4770: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
4780: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
4790: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
47a0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
47b0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
47c0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
47d0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
47e0: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
47f0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
4800: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
4810: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
4820: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
4830: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
4840: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
4850: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
4860: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
4870: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
4880: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
4890: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
48a0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
48b0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
48c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
48d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
48e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
48f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
4900: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
4910: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
4920: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
4930: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
4940: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
4950: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
4960: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
4970: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
4980: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
4990: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
49a0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
49b0: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
49c0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
49d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
49e0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
49f0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
4a00: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
4a10: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
4a20: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
4a30: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
4a40: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
4a50: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
4a60: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
4a70: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
4a80: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
4a90: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
4aa0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
4ab0: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
4ac0: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
4ad0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
4ae0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
4af0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
4b00: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
4b10: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
4b20: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
4b30: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
4b40: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
4b50: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
4b60: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
4b70: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
4b80: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
4b90: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
4ba0: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
4bb0: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
4bc0: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
4bd0: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
4be0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
4bf0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
4c00: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
4c10: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
4c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4c30: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
4c40: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
4c50: 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
4c60: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
4c70: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
4c80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
4c90: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
4ca0: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
4cb0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
4cc0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
4cd0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
4ce0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
4cf0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
4d00: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
4d10: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
4d20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
4d30: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
4d40: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
4d50: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
4d60: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
4d70: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
4d80: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
4d90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
4da0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
4db0: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
4dc0: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
4dd0: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
4de0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
4df0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
4e00: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
4e10: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
4e20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e30: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
4e40: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
4e50: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
4e60: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
4e70: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
4e80: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
4e90: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
4ea0: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
4eb0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
4ec0: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
4ed0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
4ee0: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
4ef0: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
4f00: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
4f10: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
4f20: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
4f30: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
4f40: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
4f50: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
4f60: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
4f70: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
4f80: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
4f90: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
4fa0: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
4fb0: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
4fc0: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
4fd0: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
4fe0: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
4ff0: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
5000: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
5010: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
5020: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
5030: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
5040: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
5050: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
5060: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
5070: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
5080: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
5090: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
50a0: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
50b0: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
50c0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
50d0: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
50e0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
50f0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
5100: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
5110: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
5120: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
5130: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
5140: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
5150: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
5160: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
5170: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
5180: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
5190: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
51a0: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
51b0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
51c0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
51d0: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
51e0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
51f0: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
5200: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
5210: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
5220: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
5230: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
5240: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
5250: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
5260: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
5270: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
5280: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
5290: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
52a0: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
52b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
52c0: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
52d0: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
52e0: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
52f0: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
5300: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
5310: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
5320: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
5330: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
5340: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
5350: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
5360: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
5370: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
5380: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
5390: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
53a0: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
53b0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
53c0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
53d0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
53e0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
53f0: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
5400: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
5410: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
5420: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
5430: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
5440: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
5450: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
5460: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
5470: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
5480: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
5490: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
54a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
54b0: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
54c0: 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
54d0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c  DCALL sqlite3_cl
54e0: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
54f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
5500: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
5510: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
5520: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
5530: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
5540: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
5550: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
5560: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
5570: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
5580: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
5590: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
55a0: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
55b0: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
55c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
55d0: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
55e0: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
55f0: 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  rface.** METHOD:
5600: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
5610: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
5620: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
5630: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
5640: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
5650: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
5660: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
5670: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
5680: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
5690: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
56a0: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
56b0: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
56c0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
56d0: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
56e0: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
56f0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
5700: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
5710: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
5720: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
5730: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
5740: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
5750: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
5760: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
5770: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
5780: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
5790: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
57a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
57b0: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
57c0: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
57d0: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
57e0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
57f0: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
5800: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
5810: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
5820: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
5830: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
5840: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
5850: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
5860: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
5870: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
5880: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
5890: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
58a0: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
58b0: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
58c0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
58d0: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
58e0: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
58f0: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
5900: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
5910: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
5920: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
5930: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
5940: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
5950: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
5960: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
5970: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
5980: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
5990: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
59a0: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
59b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
59c0: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
59d0: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
59e0: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
59f0: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
5a00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
5a10: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
5a20: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
5a30: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
5a40: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
5a50: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
5a60: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
5a70: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
5a80: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
5a90: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
5aa0: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
5ab0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
5ac0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
5ad0: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
5ae0: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
5af0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
5b00: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
5b10: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
5b20: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
5b30: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
5b40: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
5b50: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71  rameter of.** sq
5b60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
5b70: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
5b80: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
5b90: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
5ba0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
5bb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
5bc0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
5bd0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
5be0: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
5bf0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
5c00: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
5c10: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
5c20: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
5c30: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
5c40: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
5c50: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
5c60: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
5c70: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
5c80: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
5c90: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
5ca0: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
5cb0: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
5cc0: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
5cd0: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
5ce0: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
5cf0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
5d00: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
5d10: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
5d20: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
5d30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
5d40: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
5d50: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
5d60: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
5d70: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
5d80: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
5d90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
5da0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
5db0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
5dc0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
5dd0: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
5de0: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
5df0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
5e00: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
5e10: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
5e20: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
5e30: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
5e40: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
5e50: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
5e60: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
5e70: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
5e80: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
5e90: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
5ea0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
5eb0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
5ec0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
5ed0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
5ee0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
5ef0: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
5f00: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
5f10: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
5f20: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
5f30: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
5f40: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
5f50: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
5f60: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
5f70: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
5f80: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
5f90: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
5fa0: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
5fb0: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
5fc0: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
5fd0: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
5fe0: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
5ff0: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
6000: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
6010: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
6020: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
6030: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
6040: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
6050: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
6060: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
6070: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
6080: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
6090: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
60a0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
60b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
60c0: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
60d0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
60e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
60f0: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
6100: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
6110: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
6120: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
6130: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
6140: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
6150: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
6160: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
6170: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
6180: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
6190: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
61a0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
61b0: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
61c0: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
61d0: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
61e0: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
61f0: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
6200: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
6210: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
6220: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
6230: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
6240: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
6250: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
6260: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
6270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6280: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
6290: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
62a0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
62b0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
62c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
62d0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
62e0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
62f0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
6300: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
6310: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
6320: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
6330: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
6340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
6360: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
6370: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
6380: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63a0: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
63b0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
63c0: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
63d0: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
63e0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
63f0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
6400: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
6410: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
6420: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
6430: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
6440: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
6450: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
6460: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
6470: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
6480: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
6490: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
64a0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
64b0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
64c0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
64d0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
64e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
64f0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
6500: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6510: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
6520: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
6530: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
6540: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
6550: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
6560: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
6570: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
6580: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
6590: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
65a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
65b0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
65c0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
65d0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
65e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65f0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
6600: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
6610: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
6620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6630: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
6640: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
6650: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
6660: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
6670: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
6680: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
6690: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
66a0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
66b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
66c0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
66d0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
66e0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
66f0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6700: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
6710: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
6720: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
6730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
6740: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
6750: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
6760: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
6770: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
6780: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
6790: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
67a0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
67b0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
67c0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
67d0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
67e0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
67f0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
6800: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
6810: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6820: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
6830: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
6840: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
6850: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
6860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6870: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
6880: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
6890: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
68a0: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
68b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
68c0: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
68d0: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
68e0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
68f0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
6900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
6910: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
6920: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
6930: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
6940: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
6950: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
6960: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
6970: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
6980: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
6990: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
69a0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
69b0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
69c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
69d0: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
69e0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
69f0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
6a00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6a10: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
6a20: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
6a30: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
6a40: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6a60: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
6a70: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
6a80: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
6a90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6aa0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
6ab0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
6ac0: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
6ad0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
6ae0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
6af0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
6b00: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
6b10: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
6b20: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
6b30: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
6b40: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
6b50: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
6b60: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
6b70: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
6b80: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
6b90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6ba0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
6bb0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
6bc0: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
6bd0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
6be0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
6bf0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
6c00: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
6c10: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
6c20: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
6c30: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
6c40: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
6c50: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
6c60: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
6c70: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
6c80: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
6c90: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
6ca0: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
6cb0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
6cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6cd0: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
6ce0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
6cf0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
6d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
6d10: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
6d20: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
6d30: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
6d40: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
6d50: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
6d60: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
6d70: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
6d80: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
6d90: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
6da0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
6db0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6dc0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
6dd0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
6de0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
6df0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
6e00: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
6e10: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
6e20: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
6e30: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
6e40: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
6e50: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
6e60: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
6e70: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
6e80: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
6e90: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
6ea0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
6eb0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
6ec0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
6ed0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
6ee0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
6ef0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
6f00: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
6f10: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
6f20: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
6f30: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
6f40: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
6f50: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
6f60: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
6f70: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
6f80: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
6f90: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
6fa0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
6fb0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
6fc0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
6fd0: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
6fe0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
6ff0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
7000: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
7010: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
7020: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
7030: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
7040: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
7050: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
7060: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
7070: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
7080: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
7090: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
70a0: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
70b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
70c0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
70d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
70e0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
70f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
7100: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
7110: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7120: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7130: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
7140: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
7150: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7160: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
7170: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7180: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
7190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
71a0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
71b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
71c0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
71d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71e0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
71f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7200: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
7210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7220: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
7230: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7240: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
7250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7260: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
7270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
7280: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
7290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
72a0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
72b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
72c0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
72d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
72e0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
72f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7300: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
7310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7320: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
7330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7340: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
7350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7360: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
7370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7380: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
7390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
73a0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
73b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
73c0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
73d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
73e0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
73f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7400: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
7410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7420: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
7430: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
7440: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
7450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7460: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
7470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7480: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
7490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
74a0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
74b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
74c0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
74d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
74e0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
74f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7500: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
7510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7520: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
7530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7540: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
7550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7560: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
7570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7580: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
7590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
75a0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
75b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
75c0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
75d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
75e0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
75f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7600: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
7610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7620: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
7630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7640: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7660: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
7670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7680: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
7690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
76a0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
76b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
76c0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
76d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
76e0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
76f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7700: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
7710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7720: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
7730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7740: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
7750: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7760: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
7770: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7780: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
7790: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
77a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
77b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
77c0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
77d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
77e0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
77f0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
7800: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
7810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
7820: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
7830: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
7840: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
7850: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
7860: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
7870: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
7880: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
7890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
78a0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
78b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
78c0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
78d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
78e0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
78f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7900: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
7910: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7920: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
7930: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
7940: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
7950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7960: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
7970: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
7980: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7990: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
79a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
79b0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
79c0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
79d0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
79e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
79f0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
7a00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
7a10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
7a20: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
7a30: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
7a40: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
7a50: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
7a60: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
7a70: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
7a80: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7a90: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
7aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7ab0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
7ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7ad0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
7ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7af0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
7b00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
7b10: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
7b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7b30: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
7b40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7b50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
7b60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7b70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
7b80: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
7b90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7ba0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7bb0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7bc0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
7bd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7be0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
7bf0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7c00: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
7c10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7c20: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
7c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7c40: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
7c50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7c60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
7c70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7c80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
7c90: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
7ca0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7cb0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7cc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7cd0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
7ce0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7cf0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
7d00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7d10: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
7d20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7d30: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
7d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7d50: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
7d60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7d70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
7d80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
7da0: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
7db0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
7dc0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
7dd0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7de0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
7df0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7e00: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7e10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7e20: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
7e30: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7e40: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7e50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
7e60: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
7e70: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
7e80: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7e90: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
7ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
7eb0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
7ec0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
7ed0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
7ee0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
7ef0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
7f00: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
7f10: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
7f20: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
7f30: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
7f40: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
7f50: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
7f60: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
7f70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
7f80: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7f90: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
7fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7fb0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
7fc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
7fd0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7fe0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8000: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
8010: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
8020: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8030: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8050: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
8060: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
8070: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8080: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
80b0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
80c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
80d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
80f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
8100: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8120: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
8130: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
8140: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8160: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
8170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
8180: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8190: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
81a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
81b0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
81c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
81d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
81e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
81f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8200: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
8210: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
8220: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8240: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
8250: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
8260: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8280: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
8290: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
82a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
82b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
82c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
82d0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
82e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
82f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8300: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8310: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
8320: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8340: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
8350: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
8360: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8380: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
8390: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
83a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
83b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83c0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
83d0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
83e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
83f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8410: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
8420: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
8430: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8440: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8460: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
8470: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
8480: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8490: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
84a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
84b0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
84c0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
84d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
84e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
84f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8500: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
8510: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
8520: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8530: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
8540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8550: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
8560: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
8570: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
8580: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
8590: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
85a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
85b0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
85c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
85d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
85e0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
85f0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
8600: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
8610: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
8620: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
8630: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
8640: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
8650: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
8660: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
8670: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8680: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
8690: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
86a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
86b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
86c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
86d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
86e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
86f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8700: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8710: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
8720: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8730: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8740: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8750: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8760: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8770: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8780: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8790: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
87a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
87b0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
87c0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
87d0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
87e0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
87f0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8800: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8810: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8820: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8830: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8840: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8850: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8860: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8870: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8880: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8890: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
88a0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
88b0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
88c0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
88d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
88e0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
88f0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
8900: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
8910: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
8920: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
8930: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
8940: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
8950: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
8960: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
8970: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
8980: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
8990: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
89a0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
89b0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
89c0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
89d0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
89e0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
89f0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
8a00: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8a10: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
8a20: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
8a30: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
8a40: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
8a50: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
8a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
8a70: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
8a80: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
8a90: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
8aa0: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
8ab0: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
8ac0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
8ad0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
8ae0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
8af0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
8b00: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8b10: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
8b20: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
8b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8b40: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
8b50: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8b60: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
8b70: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8b80: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8b90: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
8ba0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8bb0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
8bc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
8bd0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
8be0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
8bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8c00: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
8c10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8c20: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
8c30: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
8c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
8c60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8c70: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
8c80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8c90: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
8ca0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
8cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8cc0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
8cd0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8ce0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
8cf0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8d00: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
8d10: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
8d20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8d30: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
8d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
8d50: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8d60: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
8d70: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
8d80: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
8d90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
8da0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8db0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
8dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8dd0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
8de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8df0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
8e00: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
8e10: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
8e20: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
8e30: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
8e40: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
8e50: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
8e60: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
8e70: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
8e80: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
8e90: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
8ea0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
8eb0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ec0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8ed0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
8ee0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
8ef0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
8f00: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
8f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8f20: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
8f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8f40: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
8f50: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
8f60: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8f70: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
8f80: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
8f90: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
8fa0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
8fb0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
8fc0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
8fd0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
8fe0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8ff0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
9000: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
9010: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
9020: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
9030: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
9040: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
9050: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
9060: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
9070: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
9080: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
9090: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
90a0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
90b0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
90c0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
90d0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
90e0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
90f0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
9100: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
9110: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
9120: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
9130: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
9140: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
9150: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
9160: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
9170: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
9180: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
9190: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
91a0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
91b0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
91c0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
91d0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
91e0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
91f0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
9200: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
9210: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
9220: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9230: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
9240: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9250: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
9260: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
9270: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
9280: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
9290: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
92a0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
92b0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
92c0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
92d0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
92e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
92f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
9300: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
9310: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
9320: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
9330: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
9340: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
9350: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
9360: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
9370: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
9380: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
9390: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
93a0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
93b0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
93c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
93d0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
93e0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
93f0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
9400: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
9410: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
9420: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
9430: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
9440: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
9450: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
9460: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
9470: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
9480: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
9490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
94a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
94b0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
94c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
94d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
94e0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
94f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
9500: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
9510: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
9520: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
9530: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
9540: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
9550: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
9560: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
9570: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
9580: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
9590: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
95a0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
95b0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
95c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
95d0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
95e0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
95f0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
9600: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
9610: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
9620: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
9630: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
9640: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
9650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
9660: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
9670: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
9680: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
9690: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
96a0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
96b0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
96c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
96d0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
96e0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
96f0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
9700: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
9710: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
9720: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
9730: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
9740: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
9750: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
9760: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
9770: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
9780: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
9790: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
97a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
97b0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
97c0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
97d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
97e0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
97f0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
9800: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
9810: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9820: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
9830: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
9840: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
9850: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
9860: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
9870: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
9880: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
9890: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
98a0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
98b0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
98c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
98d0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
98e0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
98f0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
9900: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
9910: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9920: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
9930: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
9940: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
9950: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
9960: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
9970: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
9980: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
9990: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
99a0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
99b0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
99c0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
99d0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
99e0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
99f0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
9a00: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
9a10: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
9a20: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
9a30: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
9a40: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9a50: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
9a60: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
9a70: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
9a80: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
9a90: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
9aa0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
9ab0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
9ac0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
9ad0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
9ae0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
9af0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
9b00: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
9b10: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
9b20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
9b30: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
9b40: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
9b50: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
9b60: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
9b70: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
9b80: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
9b90: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
9ba0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
9bb0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
9bc0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
9bd0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
9be0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
9bf0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9c00: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
9c10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
9c20: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
9c30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9c40: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
9c50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9c60: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
9c70: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9c80: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
9c90: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
9ca0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9cb0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
9cc0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
9cd0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
9ce0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
9cf0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
9d00: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
9d10: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
9d20: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
9d30: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
9d40: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
9d50: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
9d60: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
9d70: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
9d80: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
9d90: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
9da0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
9db0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
9dc0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
9dd0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
9de0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
9df0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
9e00: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
9e10: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
9e20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9e30: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
9e40: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
9e50: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
9e60: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9e70: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
9e80: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
9e90: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
9ea0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
9eb0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
9ec0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
9ed0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
9ee0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
9ef0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
9f00: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
9f10: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
9f20: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
9f30: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
9f40: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
9f50: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
9f60: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
9f70: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
9f80: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
9f90: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
9fa0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
9fb0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
9fc0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
9fd0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
9fe0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
9ff0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
a000: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
a010: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
a020: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
a030: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
a040: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
a050: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
a060: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
a070: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
a080: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
a090: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
a0a0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
a0b0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
a0c0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
a0d0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
a0e0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
a0f0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
a100: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
a110: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
a120: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
a130: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
a140: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
a150: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
a160: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a170: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
a180: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
a190: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
a1a0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
a1b0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
a1c0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a1d0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
a1e0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
a1f0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
a200: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
a210: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
a220: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
a230: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
a240: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
a250: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
a260: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
a270: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
a280: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a290: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
a2a0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
a2b0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
a2c0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
a2d0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
a2e0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
a2f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a300: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
a320: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
a330: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
a340: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a350: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a360: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
a370: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
a390: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a3a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
a3b0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a3c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a3d0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
a3e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a3f0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
a400: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a410: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
a420: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
a430: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
a440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
a450: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
a460: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
a470: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a480: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
a490: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
a4a0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
a4b0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a4c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
a4d0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
a4e0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
a4f0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
a500: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
a510: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
a520: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
a530: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
a540: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
a550: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
a560: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a570: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
a580: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
a590: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
a5a0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
a5b0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
a5c0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
a5d0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
a5e0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
a5f0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
a600: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
a610: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
a620: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
a630: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
a640: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a650: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
a660: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
a670: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
a680: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
a690: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
a6a0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
a6b0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
a6c0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
a6d0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
a6e0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
a6f0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
a700: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
a710: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
a720: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
a730: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
a740: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
a750: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
a760: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
a770: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
a780: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
a790: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
a7a0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
a7b0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
a7c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a7d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
a7e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
a7f0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a800: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
a810: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
a820: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
a830: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a840: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
a850: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
a860: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a870: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a880: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
a890: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a8a0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
a8b0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
a8c0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
a8d0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
a8e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
a8f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
a900: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
a910: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
a920: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
a930: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
a940: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a950: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
a960: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
a970: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
a980: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
a990: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
a9a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a9b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
a9c0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
a9d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a9e0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
a9f0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
aa00: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
aa10: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
aa20: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
aa30: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
aa40: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
aa50: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
aa60: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
aa70: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
aa80: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
aa90: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
aaa0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
aab0: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
aac0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
aad0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
aae0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
aaf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
ab00: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
ab10: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
ab20: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
ab30: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
ab40: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
ab50: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
ab60: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
ab70: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
ab80: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
ab90: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
aba0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
abb0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
abc0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
abd0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
abe0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
abf0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
ac00: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
ac10: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
ac20: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
ac30: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
ac40: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
ac50: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
ac60: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
ac70: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
ac80: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
ac90: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
aca0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
acb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
acc0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
acd0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
ace0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
acf0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
ad00: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
ad10: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
ad20: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
ad30: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
ad40: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
ad50: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
ad60: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
ad70: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
ad80: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
ad90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ada0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
adb0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
adc0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
add0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
ade0: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
adf0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ae00: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
ae10: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
ae20: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
ae30: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
ae40: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
ae50: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
ae60: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
ae70: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
ae80: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
ae90: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
aea0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
aeb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
aec0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
aed0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
aee0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
aef0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
af00: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
af10: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
af20: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
af30: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
af40: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
af50: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
af60: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
af70: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
af80: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
af90: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
afa0: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
afb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
afc0: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
afd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afe0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
aff0: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
b000: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
b010: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
b020: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
b030: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b040: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
b050: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
b060: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
b070: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
b080: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
b090: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
b0a0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
b0b0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
b0c0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
b0d0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
b0e0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
b0f0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
b100: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
b110: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
b120: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
b130: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
b140: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
b150: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b170: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b180: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b190: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
b1a0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
b1b0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
b1c0: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
b1d0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
b1e0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
b1f0: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
b200: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
b210: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
b220: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
b230: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b240: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
b250: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
b260: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
b270: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
b280: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
b290: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
b2a0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
b2b0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
b2c0: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
b2d0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
b2e0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
b2f0: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
b300: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
b310: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
b320: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
b330: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
b340: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
b350: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b360: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b370: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b380: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b390: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
b3a0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
b3b0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
b3c0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b3d0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
b3e0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
b3f0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
b400: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
b410: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
b420: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
b430: 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  L_POINTER]..**.*
b440: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b450: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
b460: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
b480: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  NAL_POINTER] opc
b490: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
b4a0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
b4b0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
b4c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b4d0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
b4e0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
b4f0: 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20   (either.** the 
b500: 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  [rollback journa
b510: 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65  l] or the [write
b520: 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72  -ahead log]) for
b530: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
b540: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
b550: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
b570: 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  LE_POINTER]..**.
b580: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b590: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
b5a0: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
b5b0: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
b5c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b5d0: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
b5e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
b5f0: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
b600: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
b610: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
b620: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
b630: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
b640: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
b650: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
b660: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
b670: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
b680: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
b690: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
b6a0: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
b6b0: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
b6c0: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
b6d0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
b6e0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
b6f0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
b700: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
b710: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
b720: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
b730: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
b740: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
b750: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
b760: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
b770: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
b780: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
b790: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
b7a0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
b7b0: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
b7c0: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
b7d0: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
b7e0: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
b7f0: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
b800: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
b810: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
b820: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
b830: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
b840: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
b850: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
b860: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
b870: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
b880: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
b890: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
b8a0: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
b8b0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
b8c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
b8d0: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
b8e0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
b8f0: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
b900: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
b910: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
b920: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
b930: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
b940: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b950: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
b960: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
b970: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
b980: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
b990: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
b9a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
b9b0: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
b9c0: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
b9d0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
b9e0: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
b9f0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
ba00: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
ba10: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
ba20: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
ba30: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
ba40: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
ba50: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
ba60: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
ba70: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
ba80: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
ba90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
baa0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
bab0: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
bac0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
bad0: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
bae0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
baf0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
bb00: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
bb10: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
bb20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
bb30: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
bb40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bb50: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
bb60: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
bb70: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
bb80: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
bb90: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
bba0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
bbb0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
bbc0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
bbd0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
bbe0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
bbf0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
bc00: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
bc10: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
bc20: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
bc30: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
bc40: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
bc50: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
bc60: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
bc70: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
bc80: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
bc90: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
bca0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
bcb0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
bcc0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
bcd0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
bce0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
bcf0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
bd00: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
bd10: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
bd20: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
bd30: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
bd40: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
bd50: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
bd60: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
bd70: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
bd80: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
bd90: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
bda0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
bdb0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
bdc0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
bdd0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
bde0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
bdf0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
be00: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
be10: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
be20: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
be30: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
be40: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
be50: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
be60: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
be70: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
be80: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
be90: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
bea0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
beb0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
bec0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
bed0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
bee0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
bef0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
bf00: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
bf10: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
bf20: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
bf30: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
bf40: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
bf50: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
bf60: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
bf70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
bf80: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
bf90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bfa0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
bfb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
bfc0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
bfd0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
bfe0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
bff0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
c000: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
c010: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
c020: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
c030: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
c040: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
c050: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
c060: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
c070: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
c080: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
c090: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
c0a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
c0b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
c0c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
c0d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
c0e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
c0f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
c100: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
c110: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
c120: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
c130: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
c140: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
c150: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
c160: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
c170: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
c180: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
c190: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
c1a0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
c1b0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
c1c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
c1d0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
c1e0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
c1f0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
c200: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
c210: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
c220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c230: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
c240: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
c250: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
c260: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
c270: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
c280: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
c290: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
c2a0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
c2b0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
c2c0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
c2d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
c2e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
c2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
c300: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
c310: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
c320: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
c330: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
c340: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c350: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
c360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
c370: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
c380: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
c390: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
c3a0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
c3b0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
c3c0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
c3d0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
c3e0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
c3f0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
c400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
c410: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
c420: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
c430: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
c440: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
c450: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
c460: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
c470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
c480: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
c490: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
c4a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
c4b0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
c4c0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
c4d0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
c4e0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
c4f0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
c500: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
c510: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
c520: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
c530: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
c540: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
c550: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
c560: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
c570: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c580: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
c590: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c5a0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
c5b0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
c5c0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
c5d0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
c5e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
c5f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
c600: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
c610: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
c620: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
c630: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
c640: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
c650: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
c660: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
c670: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
c680: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
c690: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
c6a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c6b0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
c6c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c6d0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
c6e0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c6f0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
c700: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
c710: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
c720: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
c730: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
c740: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
c750: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
c760: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
c770: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
c780: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
c790: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
c7a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
c7b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
c7c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
c7d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
c7e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
c7f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
c800: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c810: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
c820: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
c830: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
c840: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
c850: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
c860: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
c870: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
c880: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
c890: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
c8a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
c8b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
c8c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
c8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
c8e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
c8f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
c900: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
c910: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
c920: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
c930: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
c940: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
c950: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
c960: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
c970: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c980: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
c990: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c9a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c9b0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64  TER] opcode find
c9c0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
c9d0: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20  he top-level.** 
c9e0: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c  [VFSes] currentl
c9f0: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65  y in use.  ^(The
ca00: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a   argument X in.*
ca10: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  * sqlite3_file_c
ca20: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45  ontrol(db,SQLITE
ca30: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
ca40: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a  ER,X) must be.**
ca50: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74   of type "[sqlit
ca60: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68  e3_vfs] **".  Th
ca70: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20  is opcodes will 
ca80: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70  set *X.** to a p
ca90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
caa0: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a  p-level VFS.)^.*
cab0: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72  * ^When there ar
cac0: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73  e multiple VFS s
cad0: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63  hims in the stac
cae0: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66  k, this opcode f
caf0: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65  inds the.** uppe
cb00: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79  r-most shim only
cb10: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
cb20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cb30: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
cb40: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
cb50: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
cb60: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
cb70: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
cb80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
cb90: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
cba0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
cbb0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
cbc0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
cbd0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
cbe0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
cbf0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
cc00: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
cc10: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
cc20: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
cc30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
cc40: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
cc50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
cc60: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
cc70: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
cc80: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
cc90: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
cca0: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
ccb0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
ccc0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
ccd0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
cce0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
ccf0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
cd00: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
cd10: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
cd20: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
cd30: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
cd40: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
cd50: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
cd60: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
cd70: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
cd80: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
cd90: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
cda0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
cdb0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
cdc0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
cdd0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
cde0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
cdf0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
ce00: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
ce10: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
ce20: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
ce30: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ce40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ce50: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ce60: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ce70: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ce80: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
ce90: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
cea0: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
ceb0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
cec0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
ced0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
cee0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
cef0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
cf00: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
cf10: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
cf20: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
cf30: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
cf40: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
cf50: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
cf60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66  red statement if
cf70: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
cf80: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20  s NULL, or that 
cf90: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a  returns a copy.*
cfa0: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
cfb0: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74  string if the st
cfc0: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c  ring is non-NULL
cfd0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  ..** ^If the [SQ
cfe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cff0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
d000: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
d010: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
d020: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
d030: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
d040: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
d050: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
d060: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
d070: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
d080: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
d090: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
d0a0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
d0b0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
d0c0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
d0d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d0e0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
d0f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
d100: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
d110: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
d120: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
d130: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
d140: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
d150: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
d160: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
d170: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d180: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
d190: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
d1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
d1b0: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
d1c0: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
d1d0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
d1e0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
d1f0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
d200: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
d210: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
d220: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
d230: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
d240: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
d250: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
d260: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
d270: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
d280: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
d290: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
d2a0: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
d2b0: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
d2c0: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
d2d0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
d2e0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
d2f0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
d300: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
d310: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
d320: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
d330: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
d340: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
d350: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
d360: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
d370: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
d380: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
d390: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
d3a0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
d3b0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
d3c0: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
d3d0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
d3e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
d3f0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
d400: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
d410: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
d420: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
d430: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d440: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d450: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
d460: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
d470: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d480: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
d490: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
d4a0: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
d4b0: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
d4c0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
d4d0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
d4e0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
d4f0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
d500: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
d510: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
d520: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
d530: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
d540: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
d550: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
d560: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
d570: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
d580: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
d590: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
d5a0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
d5b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
d5c0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
d5d0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
d5e0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
d5f0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
d600: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
d610: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
d620: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d630: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
d640: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
d650: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d660: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
d670: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
d680: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
d690: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
d6a0: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
d6b0: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
d6c0: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
d6d0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
d6e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d6f0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
d700: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
d710: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
d720: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
d730: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
d740: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
d750: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
d760: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
d770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
d780: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
d790: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
d7a0: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
d7b0: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
d7c0: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
d7d0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
d7e0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
d7f0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
d800: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
d810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
d820: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
d830: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
d840: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
d850: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
d860: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
d870: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
d880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d890: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
d8a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d8b0: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
d8c0: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
d8d0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
d8e0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
d8f0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
d900: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
d910: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
d920: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
d930: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
d940: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
d950: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
d960: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
d970: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
d980: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
d990: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
d9a0: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
d9b0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
d9c0: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
d9d0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
d9e0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d9f0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
da00: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
da10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
da20: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
da30: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
da40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
da50: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
da60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
da70: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
da80: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
da90: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
daa0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
dab0: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
dac0: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
dad0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
dae0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
daf0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
db00: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
db10: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
db20: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
db30: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
db40: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
db50: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
db60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
db70: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
db80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
db90: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
dba0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
dbb0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
dbc0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
dbd0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
dbe0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
dbf0: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
dc00: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
dc10: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
dc20: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
dc30: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
dc40: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
dc50: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
dc60: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
dc70: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
dc80: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
dc90: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
dca0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
dcb0: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
dcc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
dcd0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
dce0: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  K] is a signal t
dcf0: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20  o the VFS layer 
dd00: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a  that it might.**
dd10: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73   be advantageous
dd20: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65   to block on the
dd30: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69   next WAL lock i
dd40: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f  f the lock is no
dd50: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  t immediately.**
dd60: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65   available.  The
dd70: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69   WAL subsystem i
dd80: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61  ssues this signa
dd90: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a  l during rare.**
dda0: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69   circumstances i
ddb0: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61  n order to fix a
ddc0: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72   problem with pr
ddd0: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e  iority inversion
dde0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
ddf0: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74  s should <em>not
de00: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66  </em> use this f
de10: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a  ile-control..**.
de20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
de30: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a  FCNTL_ZIPVFS]].*
de40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
de50: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f  NTL_ZIPVFS] opco
de60: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
de70: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79  d by zipvfs only
de80: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56  . All other.** V
de90: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
dea0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
deb0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
dec0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ded0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d  LITE_FCNTL_RBU]]
dee0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
def0: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64  FCNTL_RBU] opcod
df00: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
df10: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20   by the special 
df20: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74  VFS used by.** t
df30: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e  he RBU extension
df40: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65   only.  All othe
df50: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  r VFS should ret
df60: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
df70: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20  UND for.** this 
df80: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75  opcode.  .** </u
df90: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
dfa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
dfb0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
dfc0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
dfd0: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
dfe0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
dff0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
e000: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
e010: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
e020: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
e030: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
e040: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
e050: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
e060: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
e070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
e080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e090: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
e0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
e0b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e0c0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
e0d0: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
e0e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e0f0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
e100: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
e110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e120: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
e130: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
e140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e150: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
e160: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
e170: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e180: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
e190: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
e1a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e1b0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
e1c0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
e1d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
e1e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
e1f0: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
e200: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
e210: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
e220: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
e230: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
e240: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
e250: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
e260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
e270: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
e280: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
e290: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
e2a0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
e2b0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
e2c0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
e2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e2e0: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
e2f0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
e300: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
e310: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
e320: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
e330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e340: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
e350: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
e360: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
e370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e380: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
e390: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
e3a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e3b0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
e3c0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
e3d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e3e0: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
e3f0: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
e400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e410: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
e420: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
e430: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e440: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
e450: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
e460: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e470: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
e480: 20 20 20 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64          28../* d
e490: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
e4a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e4b0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
e4c0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
e4d0: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
e4e0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
e4f0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
e500: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
e510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
e520: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
e530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
e540: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
e550: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
e560: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
e570: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
e580: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
e590: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
e5a0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
e5b0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
e5c0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
e5d0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
e5e0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
e5f0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
e600: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
e610: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
e620: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
e630: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
e640: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
e650: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
e660: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
e670: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
e680: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
e690: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
e6a0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
e6b0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
e6c0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
e6d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
e6e0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
e6f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e700: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
e710: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
e720: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e730: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
e740: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
e750: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
e760: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
e770: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
e780: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
e790: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
e7a0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
e7b0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
e7c0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
e7d0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e7e0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
e7f0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
e800: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
e810: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
e820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
e830: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
e840: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
e850: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
e860: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
e870: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e880: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
e890: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
e8a0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
e8b0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
e8c0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
e8d0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
e8e0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
e8f0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
e900: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e910: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
e920: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
e930: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
e940: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
e950: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
e960: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
e970: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
e980: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
e990: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e9a0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e9b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e9c0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e9d0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e9e0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e9f0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
ea00: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
ea10: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
ea20: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
ea30: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
ea40: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
ea50: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
ea60: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
ea70: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
ea80: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
ea90: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
eaa0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
eab0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
eac0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
ead0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
eae0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
eaf0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
eb00: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
eb10: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
eb20: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
eb30: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
eb40: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
eb50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
eb60: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
eb70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
eb80: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
eb90: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
eba0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
ebb0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
ebc0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
ebd0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
ebe0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
ebf0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
ec00: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
ec10: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
ec20: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
ec30: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
ec40: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
ec50: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
ec60: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
ec70: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
ec80: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
ec90: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
eca0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
ecb0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
ecc0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
ecd0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
ece0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
ecf0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
ed00: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
ed10: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
ed20: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
ed30: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
ed40: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
ed50: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
ed60: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
ed70: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
ed80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
ed90: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
eda0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
edb0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
edc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
edd0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
ede0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
edf0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
ee00: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
ee10: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
ee20: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
ee30: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
ee40: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
ee50: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
ee60: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
ee70: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
ee80: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
ee90: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
eea0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
eeb0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
eec0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
eed0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
eee0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
eef0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ef00: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ef10: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ef20: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ef30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ef40: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ef50: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ef60: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ef70: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ef80: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
ef90: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
efa0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
efb0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
efc0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
efd0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
efe0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eff0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
f000: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
f010: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
f020: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
f030: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
f040: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
f050: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
f060: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
f070: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
f080: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
f090: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
f0a0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
f0b0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
f0c0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
f0d0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
f0e0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
f0f0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
f100: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
f110: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
f120: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f130: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
f140: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
f150: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
f160: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
f170: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
f180: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
f190: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
f1a0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
f1b0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
f1c0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
f1d0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
f1e0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
f1f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
f200: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
f210: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
f220: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
f230: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
f240: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
f250: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
f260: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
f270: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
f280: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
f290: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
f2a0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
f2b0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
f2c0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
f2d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f2e0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
f2f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
f300: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
f310: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
f320: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
f330: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
f340: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
f350: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
f360: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
f370: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
f380: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
f390: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
f3a0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
f3b0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
f3c0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
f3d0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
f3e0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
f3f0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
f400: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
f410: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
f420: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
f430: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
f440: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
f450: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
f460: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
f470: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
f480: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
f490: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
f4a0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
f4b0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
f4c0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
f4d0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f4e0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f4f0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f500: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f510: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f520: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f530: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f540: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f550: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f560: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f570: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f580: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f590: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f5a0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f5b0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f5c0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f5d0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f5e0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f5f0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f600: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f610: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f620: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f630: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f640: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f650: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f660: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f670: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f680: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f690: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f6a0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f6b0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f6c0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f6d0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f6e0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f6f0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f700: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f710: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f720: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f730: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f740: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f750: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f760: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f770: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f780: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f790: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f7a0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f7b0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f7c0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f7d0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f7e0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f7f0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f800: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f810: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f820: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f830: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f840: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f850: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f860: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f870: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f880: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f890: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f8a0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f8b0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f8c0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f8d0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f8e0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f8f0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f900: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f910: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f920: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f930: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f940: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f950: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f960: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f970: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f980: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f990: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f9a0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f9b0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f9c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f9d0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f9e0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f9f0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
fa00: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
fa10: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
fa20: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
fa30: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
fa40: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
fa50: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
fa60: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
fa70: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
fa80: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
fa90: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
faa0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
fab0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
fac0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
fad0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
fae0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
faf0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
fb00: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
fb10: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
fb20: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
fb30: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
fb40: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
fb50: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
fb60: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
fb70: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
fb80: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
fb90: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
fba0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
fbb0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
fbc0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
fbd0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
fbe0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
fbf0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
fc00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
fc10: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
fc20: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
fc30: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
fc40: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
fc50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fc60: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
fc70: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
fc80: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
fc90: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
fca0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
fcb0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
fcc0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
fcd0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
fce0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
fcf0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
fd00: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
fd10: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
fd20: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
fd30: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
fd40: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
fd50: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
fd60: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
fd70: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
fd80: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
fd90: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
fda0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
fdb0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
fdc0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
fdd0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
fde0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
fdf0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
fe00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
fe10: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
fe20: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
fe30: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
fe40: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
fe50: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
fe60: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
fe70: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
fe80: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
fe90: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
fea0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
feb0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
fec0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
fed0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
fee0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
fef0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
ff00: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
ff10: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
ff20: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
ff30: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
ff40: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
ff50: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
ff60: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
ff70: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
ff80: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
ff90: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
ffa0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
ffb0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
ffc0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
ffd0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
ffe0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
fff0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
10000 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
10010 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
10020 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
10030 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
10040 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
10050 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
10060 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
10070 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
10080 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
10090 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
100a0 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
100b0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
100c0 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
100d0 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
100e0 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
100f0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
10100 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
10110 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
10120 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
10130 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
10140 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
10150 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
10160 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
10170 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
10180 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
10190 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
101a0 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
101b0 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
101c0 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
101d0 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
101e0 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
101f0 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
10200 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
10210 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
10220 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
10230 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
10240 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
10250 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
10260 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
10270 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
10280 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
10290 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
102a0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
102b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
102c0 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
102d0 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
102e0 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
102f0 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
10300 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
10310 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
10320 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
10330 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
10340 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
10350 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
10360 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
10370 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
10380 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
10390 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
103a0 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
103b0 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
103c0 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
103d0 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
103e0 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
103f0 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
10400 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
10410 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
10420 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
10430 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
10440 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
10450 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
10460 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
10470 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
10480 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
10490 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
104a0 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
104b0 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
104c0 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
104d0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
104e0 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
104f0 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
10500 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
10510 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
10520 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
10530 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
10540 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
10550 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
10560 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
10570 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
10580 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
10590 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
105a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
105b0 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
105c0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
105d0 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
105e0 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
105f0 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
10600 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
10610 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
10620 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
10630 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
10640 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
10650 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
10660 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
10670 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
10680 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
10690 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
106a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
106b0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
106c0 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
106d0 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
106e0 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
106f0 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
10700 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10710 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
10720 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
10730 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
10740 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10750 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
10760 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
10770 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
10780 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
10790 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
107a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
107b0 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
107c0 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
107d0 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
107e0 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
107f0 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
10800 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10810 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10820 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
10830 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
10840 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10850 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10860 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10870 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
10880 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
10890 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
108a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
108b0 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
108c0 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
108d0 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
108e0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
108f0 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
10900 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
10910 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
10920 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
10930 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
10940 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
10950 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
10960 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
10970 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
10980 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
10990 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
109a0 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
109b0 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
109c0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
109d0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
109e0 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
109f0 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
10a00 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
10a10 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
10a20 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
10a30 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
10a40 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
10a50 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
10a60 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
10a70 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
10a80 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
10a90 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
10aa0 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
10ab0 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
10ac0 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
10ad0 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
10ae0 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
10af0 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
10b00 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
10b10 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10b20 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
10b30 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
10b40 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
10b50 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
10b60 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
10b70 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
10b80 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
10b90 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
10ba0 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
10bb0 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
10bc0 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
10bd0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
10be0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10bf0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
10c00 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10c10 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
10c20 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
10c30 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10c40 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10c50 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10c60 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
10c70 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
10c80 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10c90 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
10ca0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
10cb0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
10cc0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
10cd0 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
10ce0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10cf0 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
10d00 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
10d10 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
10d20 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
10d30 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
10d40 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
10d50 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
10d60 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
10d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10d80 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
10d90 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
10da0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
10db0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
10dc0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
10dd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10de0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
10df0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
10e00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10e10 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10e20 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
10e30 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
10e40 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
10e50 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
10e60 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
10e70 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10e80 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
10e90 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
10ea0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
10eb0 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
10ec0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10ed0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10ee0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10ef0 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10f00 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10f10 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10f20 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
10f30 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
10f40 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
10f50 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
10f60 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
10f70 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
10f80 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10f90 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10fa0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10fb0 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
10fc0 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
10fd0 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
10fe0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10ff0 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
11000 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
11010 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
11020 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
11030 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
11040 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
11050 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
11060 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
11070 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
11080 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
11090 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
110a0 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
110b0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
110c0 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
110d0 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
110e0 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
110f0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
11100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11110 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
11120 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
11130 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
11140 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
11150 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
11160 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
11170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11180 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
11190 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
111a0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
111b0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
111c0 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
111d0 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
111e0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
111f0 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
11200 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
11210 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
11220 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
11230 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
11240 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
11250 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
11260 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
11270 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
11280 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
11290 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
112a0 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
112b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
112c0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
112d0 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
112e0 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
112f0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
11300 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
11310 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
11320 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
11330 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
11340 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
11350 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
11360 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
11370 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
11380 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
11390 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
113a0 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
113b0 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
113c0 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
113d0 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
113e0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
113f0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
11400 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
11410 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
11420 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
11430 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
11440 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
11450 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
11460 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
11470 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
11480 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
11490 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
114a0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
114b0 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
114c0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
114d0 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
114e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
114f0 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
11500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11510 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
11520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11530 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
11540 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
11550 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
11560 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
11570 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
11580 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
11590 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
115a0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
115b0 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
115c0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
115d0 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
115e0 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
115f0 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
11600 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
11610 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
11620 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
11630 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
11640 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
11650 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
11660 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
11670 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
11680 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11690 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
116a0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
116b0 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
116c0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
116d0 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
116e0 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
116f0 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
11700 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
11710 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
11720 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
11730 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11740 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
11750 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
11760 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
11770 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
11780 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
11790 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
117a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
117b0 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
117c0 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
117d0 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
117e0 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
117f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
11800 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
11810 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
11820 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
11830 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
11840 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
11850 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11860 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
11870 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
11880 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
11890 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
118a0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
118b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
118c0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
118d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
118e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
118f0 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
11900 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11910 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
11920 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
11930 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
11940 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
11950 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
11960 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11970 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
11980 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11990 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
119a0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
119b0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
119c0 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
119d0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
119e0 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
119f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11a00 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
11a10 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
11a20 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11a30 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
11a40 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
11a50 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
11a60 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
11a70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
11a80 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
11a90 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
11aa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11ab0 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
11ac0 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
11ad0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
11ae0 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
11af0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
11b00 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
11b10 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
11b20 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
11b30 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
11b40 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
11b50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11b60 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
11b70 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
11b80 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
11b90 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
11ba0 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
11bb0 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
11bc0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
11bd0 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
11be0 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
11bf0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
11c00 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
11c10 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11c20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
11c30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
11c40 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
11c50 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
11c70 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11c80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11c90 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
11ca0 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
11cb0 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
11cc0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11cd0 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
11ce0 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
11cf0 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
11d00 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
11d10 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
11d20 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
11d30 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
11d40 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
11d50 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
11d60 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11d70 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
11d80 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11d90 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
11da0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
11db0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
11dc0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
11dd0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
11de0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
11df0 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
11e00 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11e10 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11e20 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
11e30 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
11e40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
11e50 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
11e60 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
11e70 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11e80 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
11e90 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
11ea0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
11eb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
11ec0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
11ed0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
11ee0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
11ef0 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
11f00 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11f10 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11f20 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11f30 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
11f40 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
11f50 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
11f60 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
11f70 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
11f80 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11f90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11fa0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
11fb0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11fc0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
11fd0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11fe0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11ff0 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
12000 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
12010 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
12020 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
12030 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
12040 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
12050 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
12060 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
12070 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
12080 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
12090 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
120a0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
120b0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
120c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
120d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
120e0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
120f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12100 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
12110 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
12120 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
12130 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
12140 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
12150 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
12160 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
12170 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12180 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
12190 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
121a0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
121b0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
121c0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
121d0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
121e0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
121f0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
12200 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
12210 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
12220 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
12230 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
12240 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
12250 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
12260 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
12270 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
12280 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
12290 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
122a0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
122b0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
122c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
122d0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
122e0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
122f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
12300 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
12310 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
12320 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
12330 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
12340 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
12350 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
12360 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
12370 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
12380 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
12390 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
123a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
123b0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
123c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
123d0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
123e0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
123f0 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
12400 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
12410 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12420 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
12430 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
12440 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
12450 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
12460 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
12470 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
12480 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
12490 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
124a0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
124b0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
124c0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
124d0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
124e0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
124f0 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
12500 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
12510 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
12520 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
12530 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
12540 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
12550 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
12560 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12570 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
12580 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
12590 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
125a0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
125b0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
125c0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
125d0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
125e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
125f0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12600 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
12610 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
12620 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12630 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
12640 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
12650 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
12660 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53  ** failure..*/.S
12670 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12680 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
12690 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
126a0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
126b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
126c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75  CALL sqlite3_shu
126d0 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  tdown(void);.SQL
126e0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
126f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
12700 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
12710 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
12720 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
12730 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
12740 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
12750 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
12760 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
12770 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
12780 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12790 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
127a0 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
127b0 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
127c0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
127d0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
127e0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
127f0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
12800 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
12810 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
12820 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
12830 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
12840 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
12850 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
12860 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
12870 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
12880 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
12890 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
128a0 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
128b0 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
128c0 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
128d0 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
128e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
128f0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
12900 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
12910 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
12920 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
12930 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
12940 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
12950 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
12960 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
12970 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12980 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
12990 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
129a0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
129b0 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
129c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
129d0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
129e0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
129f0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
12a00 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
12a10 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
12a20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
12a30 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
12a40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
12a50 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
12a60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12a70 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
12a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
12a90 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
12aa0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
12ab0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
12ac0 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
12ad0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
12ae0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
12af0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
12b00 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
12b10 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
12b20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
12b30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12b40 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
12b50 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
12b60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12b70 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
12b80 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
12b90 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
12ba0 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
12bb0 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
12bc0 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
12bd0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
12be0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
12bf0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
12c00 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
12c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
12c20 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12c30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
12c40 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
12c50 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
12c60 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
12c70 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
12c80 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
12c90 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
12ca0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
12cb0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
12cc0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
12cd0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
12ce0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
12cf0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
12d00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
12d10 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  int SQLITE_CDECL
12d20 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12d30 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
12d40 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
12d50 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
12d60 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
12d70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
12d80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12d90 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
12da0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
12db0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
12dc0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12dd0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
12de0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12df0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
12e00 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
12e10 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
12e20 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
12e30 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
12e40 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
12e50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12e60 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
12e70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12e80 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12e90 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12ea0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12eb0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
12ec0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
12ed0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12ee0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
12ef0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
12f00 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
12f10 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
12f20 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
12f30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12f40 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
12f50 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
12f60 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12f70 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
12f80 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12f90 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12fa0 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
12fb0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12fc0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
12fd0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
12fe0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
12ff0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
13000 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
13010 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
13020 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62  CDECL sqlite3_db
13030 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
13040 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
13050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13060 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
13070 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
13080 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
13090 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
130a0 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
130b0 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
130c0 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
130d0 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
130e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
130f0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
13100 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
13110 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
13120 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
13130 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
13140 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13150 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
13160 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
13170 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13180 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
13190 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
131a0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
131b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
131c0 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
131d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
131e0 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
131f0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
13200 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
13210 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
13220 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
13230 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
13240 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
13250 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
13260 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
13270 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
13280 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
13290 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
132a0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
132b0 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
132c0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
132d0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
132e0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
132f0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
13300 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
13310 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
13320 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
13330 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
13340 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
13350 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
13360 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
13370 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
13380 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
13390 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
133a0 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
133b0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
133c0 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
133d0 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
133e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
133f0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
13400 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
13410 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
13420 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
13430 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
13440 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
13450 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
13460 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
13470 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
13480 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
13490 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
134a0 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
134b0 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
134c0 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
134d0 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
134e0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
134f0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
13500 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
13510 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
13520 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
13530 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
13540 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
13550 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
13560 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
13570 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
13580 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
13590 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
135a0 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
135b0 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
135c0 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
135d0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
135e0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
135f0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
13600 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
13610 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
13620 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
13630 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
13640 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
13650 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
13660 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
13670 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
13680 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
13690 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
136a0 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
136b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
136c0 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
136d0 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
136e0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
136f0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
13700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13710 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
13720 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
13730 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
13740 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
13750 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
13760 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
13770 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
13780 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
13790 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
137a0 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
137b0 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
137c0 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
137d0 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
137e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
137f0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
13800 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
13810 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
13820 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
13830 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
13840 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
13850 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
13860 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
13870 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
13880 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
13890 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
138a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
138b0 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
138c0 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
138d0 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
138e0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
138f0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
13900 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
13910 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
13920 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
13930 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
13940 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
13950 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
13960 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
13970 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
13980 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
13990 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
139a0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
139b0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
139c0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
139d0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
139e0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
139f0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
13a00 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
13a10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
13a20 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
13a30 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
13a40 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
13a50 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
13a60 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
13a70 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
13a80 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
13a90 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
13aa0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
13ab0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
13ac0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13ad0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
13ae0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
13af0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
13b00 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
13b10 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
13b20 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
13b30 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
13b40 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
13b50 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
13b60 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
13b70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13b80 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
13b90 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
13ba0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
13bb0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
13bc0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
13bd0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
13be0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
13bf0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
13c00 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
13c10 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
13c20 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
13c30 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
13c40 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
13c50 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
13c60 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
13c70 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
13c80 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
13c90 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
13ca0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
13cb0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
13cc0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
13cd0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
13ce0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
13cf0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
13d00 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
13d10 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
13d20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
13d30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
13d40 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
13d50 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
13d60 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
13d70 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
13d80 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
13d90 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
13da0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
13db0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
13dc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13dd0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
13de0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
13df0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
13e00 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
13e10 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
13e20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
13e30 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
13e40 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13e50 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
13e60 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
13e70 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
13e80 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
13e90 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
13ea0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
13eb0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
13ec0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
13ed0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13ee0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13ef0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
13f00 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
13f10 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
13f20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
13f30 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
13f40 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
13f50 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
13f60 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
13f70 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
13f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13f90 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
13fa0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
13fb0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
13fc0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
13fd0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
13fe0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
13ff0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
14000 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
14010 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
14020 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
14030 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
14040 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
14050 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
14060 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
14070 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14080 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
14090 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
140a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
140b0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
140c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
140d0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
140e0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
140f0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
14100 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
14110 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
14120 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
14130 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
14140 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
14150 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
14160 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
14170 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
14180 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
14190 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
141a0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
141b0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
141c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
141d0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
141e0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
141f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
14200 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
14210 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14220 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
14230 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
14240 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
14250 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
14260 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
14270 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
14280 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
14290 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
142a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
142b0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
142c0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
142d0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
142e0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
142f0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
14300 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
14310 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
14320 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14330 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14340 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14350 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14360 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14370 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
14380 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
14390 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
143a0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
143b0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
143c0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
143d0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
143e0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
143f0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
14400 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
14410 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
14420 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14430 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
14440 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
14450 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14460 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14470 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
14480 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
14490 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
144a0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
144b0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
144c0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
144d0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
144e0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
144f0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
14500 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
14510 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
14520 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
14530 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
14540 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14550 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
14560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
14570 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
14580 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
14590 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
145a0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
145b0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
145c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
145d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
145e0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
145f0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
14600 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
14610 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
14620 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
14630 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14640 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
14650 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
14660 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
14670 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
14680 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
14690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
146a0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
146b0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
146c0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
146d0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
146e0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
146f0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14700 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14710 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
14720 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
14730 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
14740 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
14750 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14760 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14770 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14780 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14790 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
147a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
147b0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
147c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
147d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
147e0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
147f0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
14800 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14810 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
14820 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
14830 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
14840 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
14850 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
14860 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14870 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
14880 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
14890 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
148a0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
148b0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
148c0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
148d0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
148e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
148f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
14900 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
14910 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
14920 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
14930 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
14940 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14950 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
14960 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
14970 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
14980 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
14990 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
149a0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
149b0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
149c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
149d0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
149e0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
149f0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
14a00 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
14a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
14a20 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
14a30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14a40 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
14a50 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
14a60 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
14a70 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14a80 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14a90 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14aa0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14ab0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14ac0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14ad0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14ae0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
14af0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
14b00 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14b10 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
14b20 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
14b30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
14b40 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
14b50 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
14b60 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14b70 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
14b80 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
14b90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14ba0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
14bb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14bc0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
14bd0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14be0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
14bf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14c00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14c10 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
14c20 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14c30 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14c40 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14c50 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
14c60 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
14c70 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
14c80 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
14c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14ca0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14cb0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
14cc0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
14cd0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
14ce0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
14cf0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
14d00 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
14d10 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
14d20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
14d30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
14d40 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14d50 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
14d60 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
14d70 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
14d80 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
14d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14da0 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
14db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14dc0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
14dd0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14de0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
14df0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14e00 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14e10 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14e20 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14e30 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14e40 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14e50 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14e60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
14e70 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
14e80 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
14e90 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14ea0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
14eb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14ec0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14ed0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14ee0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14ef0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
14f00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
14f10 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
14f20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
14f30 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
14f40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
14f50 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
14f60 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
14f70 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
14f80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14f90 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14fa0 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
14fb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14fc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14fd0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14fe0 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
14ff0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
15000 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15010 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
15020 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
15030 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
15040 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
15050 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
15060 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15070 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
15080 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
15090 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
150a0 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
150b0 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
150c0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
150d0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
150e0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
150f0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
15100 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15110 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
15120 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
15130 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
15140 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
15150 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
15160 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
15170 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
15180 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
15190 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
151a0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
151b0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
151c0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
151d0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
151e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
151f0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
15200 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
15210 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
15220 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
15230 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
15240 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
15250 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
15260 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15270 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
15280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
15290 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
152a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
152b0 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
152c0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
152d0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
152e0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
152f0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
15300 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
15310 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
15320 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
15330 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15340 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
15350 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
15360 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
15370 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
15380 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
15390 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
153a0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
153b0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
153c0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
153d0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
153e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
153f0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
15400 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
15410 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15420 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
15430 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
15440 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
15450 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
15460 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
15470 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
15480 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
15490 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
154a0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
154b0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
154c0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
154d0 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
154e0 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
154f0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
15500 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
15510 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
15520 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
15530 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
15540 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
15550 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
15560 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
15570 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15580 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
15590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
155a0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
155b0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
155c0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
155d0 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
155e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
155f0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
15600 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
15610 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
15620 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15630 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
15640 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
15650 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
15660 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
15670 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
15680 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
15690 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
156a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
156b0 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
156c0 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
156d0 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
156e0 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
156f0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
15700 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15710 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15720 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15730 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
15740 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
15750 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15760 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
15770 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f  specifies a memo
15780 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20  ry pool.** that 
15790 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
157a0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
157b0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
157c0 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
157d0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
157e0 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
157f0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15800 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f  n option is a no
15810 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63  -op if an applic
15820 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
15830 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
15840 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
15850 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ded using the [S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15870 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65  CHE2]..** ^There
15880 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
15890 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
158a0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
158b0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
158c0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
158d0 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74  memory (pMem), t
158e0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
158f0 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
15900 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
15910 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65   number of cache
15920 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   lines (N)..** T
15930 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
15940 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
15950 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
15960 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
15970 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
15980 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
15990 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
159a0 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
159b0 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
159c0 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
159d0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
159e0 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
159f0 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
15a00 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
15a10 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45  ed using [SQLITE
15a20 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15a30 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73  DRSZ]..** ^It is
15a40 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
15a50 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
15a60 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20   memory,.** for 
15a70 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  the sz parameter
15a80 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68   to be larger th
15a90 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54  an necessary.  T
15aa0 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d  he pMem.** argum
15ab0 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68  ent must be eith
15ac0 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
15ad0 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  r or a pointer t
15ae0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  o an 8-byte.** a
15af0 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
15b00 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
15b10 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f  st sz*N bytes, o
15b20 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73  therwise.** subs
15b30 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
15b40 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
15b50 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e   ^When pMem is n
15b60 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
15b70 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75  will strive to u
15b80 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
15b90 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74  ovided.** to sat
15ba0 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20  isfy page cache 
15bb0 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62  needs, falling b
15bc0 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ack to [sqlite3_
15bd0 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20  malloc()] if.** 
15be0 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  a page cache lin
15bf0 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e  e is larger than
15c00 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20   sz bytes or if 
15c10 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20  all of the pMem 
15c20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68  buffer.** is exh
15c30 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70  austed..** ^If p
15c40 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  Mem is NULL and 
15c50 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  N is non-zero, t
15c60 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73  hen each databas
15c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15c80 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20  does an initial 
15c90 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  bulk allocation 
15ca0 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
15cb0 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73  emory.** from [s
15cc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15cd0 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20   sufficient for 
15ce0 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66  N cache lines if
15cf0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f   N is positive o
15d00 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20  r.** of -1024*N 
15d10 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65  bytes if N is ne
15d20 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64  gative, . ^If ad
15d30 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
15d40 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
15d50 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
15d60 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
15d70 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a  by the initial.*
15d80 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  * allocation, th
15d90 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  en SQLite goes t
15da0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
15db0 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20  c()] separately 
15dc0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69  for each.** addi
15dd0 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e  tional cache lin
15de0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
15e00 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
15e10 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
15e20 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15e40 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
15e50 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
15e60 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
15e70 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
15e80 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
15e90 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
15ea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15eb0 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
15ec0 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
15ed0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
15ee0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a  _SCRATCH] and.**
15ef0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15f00 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
15f10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15f20 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
15f30 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15f40 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
15f50 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
15f60 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
15f70 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
15f80 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
15f90 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
15fa0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
15fb0 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
15fc0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
15fd0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15fe0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
16000 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
16010 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
16020 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
16030 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
16040 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
16050 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
16060 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
16070 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
16080 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
16090 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
160a0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
160b0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
160c0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
160d0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
160e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
160f0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
16100 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
16110 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
16120 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
16130 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
16140 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
16150 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
16160 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
16170 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
16180 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
16190 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
161a0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
161b0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
161c0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
161d0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
161e0 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
161f0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
16200 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
16210 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
16220 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
16230 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
16240 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
16250 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
16260 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
16270 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
16280 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
16290 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
162a0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
162b0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
162c0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
162d0 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
162e0 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
162f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16300 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
16310 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
16320 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16330 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16340 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
16350 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16360 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
16370 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
16380 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
16390 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
163a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
163b0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
163c0 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
163d0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
163e0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
163f0 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
16400 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
16410 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
16420 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
16430 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
16440 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
16450 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
16460 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
16470 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
16480 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
16490 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
164a0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
164b0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
164c0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
164d0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
164e0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
164f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
16500 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16510 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
16520 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
16530 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
16540 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
16550 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
16560 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
16570 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
16580 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
16590 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
165a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
165b0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
165c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
165d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
165e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
165f0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
16600 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
16610 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
16620 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16630 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
16640 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16650 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16660 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16670 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
16680 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
16690 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
166a0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
166b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
166c0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
166d0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
166e0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
166f0 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
16700 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
16710 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
16720 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
16730 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
16740 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
16750 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
16760 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
16770 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
16780 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
16790 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
167a0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
167b0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
167c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
167d0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
167e0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
167f0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
16800 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
16810 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
16820 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
16830 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
16840 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
16850 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
16860 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
16870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
16880 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
16890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
168a0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
168b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
168c0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
168d0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
168e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
168f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
16900 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16910 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
16920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16930 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16940 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
16950 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
16960 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
16970 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
16980 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
16990 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
169a0 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
169b0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
169c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
169d0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
169e0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
169f0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
16a00 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
16a10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16a20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
16a30 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
16a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
16a50 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
16a60 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
16a70 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
16a80 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
16a90 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
16aa0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16ab0 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
16ac0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
16ad0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
16ae0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
16af0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
16b00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
16b10 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
16b20 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
16b30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16b40 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
16b50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16b60 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
16b70 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
16b80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16b90 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
16ba0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16bb0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
16bc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
16bd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16be0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
16bf0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
16c00 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
16c10 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
16c20 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
16c30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
16c40 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
16c50 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
16c60 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16c70 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16c80 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
16c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16ca0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
16cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16cc0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
16cd0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
16ce0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16cf0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
16d00 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16d10 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
16d20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
16d30 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16d40 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
16d50 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
16d60 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
16d70 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
16d80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
16d90 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
16da0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
16dc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16dd0 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
16de0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
16df0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
16e00 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
16e10 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
16e20 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
16e30 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
16e40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e50 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
16e60 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
16e70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
16e80 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
16e90 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
16ea0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
16eb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
16ec0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
16ed0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
16ee0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
16ef0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
16f00 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
16f10 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
16f20 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
16f30 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
16f40 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
16f50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
16f60 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
16f70 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
16f80 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
16f90 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
16fa0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
16fb0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
16fc0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16fd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16fe0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
16ff0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
17000 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17010 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
17020 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
17030 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
17040 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
17050 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
17060 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
17070 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
17080 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
17090 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
170a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
170b0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
170c0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
170d0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
170e0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
170f0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
17100 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
17110 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
17120 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
17130 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
17140 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
17150 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
17160 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
17170 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
17180 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
17190 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
171a0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
171b0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
171c0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
171d0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
171e0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
171f0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
17200 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
17210 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
17220 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
17230 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
17240 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
17250 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
17260 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
17270 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
17280 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
17290 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
172a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
172b0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
172c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
172d0 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
172e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
172f0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
17300 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
17310 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
17320 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
17330 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
17340 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
17350 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
17360 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
17370 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
17380 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
17390 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
173a0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
173b0 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
173c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
173d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
173e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
173f0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
17400 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
17410 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
17420 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
17430 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
17440 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
17450 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
17460 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
17470 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
17480 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
17490 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
174a0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
174b0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
174c0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
174d0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
174e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
174f0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
17500 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
17510 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
17520 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17530 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
17540 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
17550 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
17560 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
17570 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
17580 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
17590 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
175a0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
175b0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
175c0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
175d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
175e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
175f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
17600 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17610 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
17620 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
17630 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17640 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17650 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
17660 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
17670 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
17680 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
17690 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
176a0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
176b0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
176c0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
176d0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
176e0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
176f0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
17700 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
17710 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
17720 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
17730 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
17740 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
17750 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
17760 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17770 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
17780 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
17790 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
177a0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
177b0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
177c0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
177d0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
177e0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
177f0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
17800 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
17810 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
17820 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
17830 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
17840 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
17850 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
17860 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
17870 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
17880 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
17890 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
178a0 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
178b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
178c0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
178d0 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
178e0 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
178f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
17900 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17910 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
17920 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
17930 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
17940 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17950 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
17960 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17970 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
17980 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
17990 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
179a0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
179b0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
179c0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
179d0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
179e0 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
179f0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
17a00 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
17a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17a20 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
17a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
17a40 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
17a50 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
17a60 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
17a70 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
17a80 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
17a90 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
17aa0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
17ab0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
17ac0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17ad0 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
17ae0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
17af0 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
17b00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
17b10 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
17b20 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
17b30 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
17b40 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
17b50 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
17b60 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
17b70 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
17b80 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
17b90 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
17ba0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
17bb0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
17bc0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
17bd0 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
17be0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
17bf0 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
17c00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17c10 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
17c20 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17c30 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
17c40 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
17c50 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
17c60 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
17c70 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
17c80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
17c90 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
17ca0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
17cb0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
17cc0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
17cd0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
17ce0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17cf0 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
17d00 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
17d10 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
17d20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17d30 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
17d40 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
17d50 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
17d60 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17d70 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
17d80 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
17d90 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
17da0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
17db0 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
17dc0 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
17dd0 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
17de0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
17df0 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
17e00 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
17e10 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
17e20 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
17e30 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
17e40 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
17e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17e60 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
17e70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
17e80 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
17e90 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
17ea0 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
17eb0 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
17ec0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
17ed0 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
17ee0 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
17ef0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
17f00 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
17f10 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
17f20 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
17f30 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
17f40 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
17f50 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
17f60 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
17f70 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
17f80 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
17f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17fa0 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
17fb0 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
17fc0 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
17fd0 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
17fe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
17ff0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
18000 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
18010 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
18020 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
18030 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
18040 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
18050 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
18060 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
18070 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
18080 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
18090 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
180a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
180b0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
180c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
180d0 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
180e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
180f0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
18100 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
18110 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
18120 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
18130 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
18140 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
18150 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
18160 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
18170 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18180 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
18190 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
181a0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
181b0 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
181c0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
181d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
181e0 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
181f0 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
18200 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
18210 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
18220 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
18230 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
18240 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
18250 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
18260 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
18270 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
18280 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
18290 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
182a0 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
182b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
182c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
182d0 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
182e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
182f0 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
18300 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
18310 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
18320 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
18330 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
18340 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
18350 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18360 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
18370 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
18380 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
18390 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
183a0 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
183b0 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
183c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
183d0 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
183e0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
183f0 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
18400 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
18410 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
18420 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
18430 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
18440 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
18450 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18460 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
18470 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
18480 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
18490 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
184a0 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
184b0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
184c0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
184d0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
184e0 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
184f0 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
18500 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
18510 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
18520 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
18530 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
18540 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
18550 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
18560 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18570 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
18580 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18590 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
185a0 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
185b0 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
185c0 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
185d0 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
185e0 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
185f0 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
18600 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
18610 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
18620 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
18630 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
18640 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
18650 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
18660 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
18670 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
18680 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
18690 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
186a0 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  e..** </dl>.*/.#
186b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
186c0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
186d0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
186e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
186f0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
18700 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
18710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18720 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
18730 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
18740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18750 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
18760 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
18770 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
18780 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18790 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
187a0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
187b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
187c0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
187d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
187e0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
187f0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
18800 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
18810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
18820 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
18830 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18840 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18850 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18860 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
18870 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
18880 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
18890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
188a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
188b0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
188c0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
188d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
188e0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
188f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
18900 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18910 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18920 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
18930 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18940 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
18950 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
18960 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
18970 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
18980 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
18990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
189a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
189b0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
189c0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
189d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
189e0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
189f0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18a00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
18a10 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
18a20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
18a30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a40 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
18a50 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
18a60 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
18a70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
18a80 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
18a90 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18ab0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
18ac0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18ad0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18ae0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18af0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
18b00 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
18b10 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
18b20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18b30 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
18b40 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
18b50 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18b60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18b70 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
18b80 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
18b90 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
18bb0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
18bc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
18bd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
18be0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18bf0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
18c00 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
18c10 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
18c20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18c30 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
18c40 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
18c50 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
18c60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18c70 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
18c80 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
18c90 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
18ca0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18cb0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
18cc0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
18cd0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
18ce0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
18cf0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
18d00 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
18d10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18d20 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
18d30 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
18d40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18d50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
18d60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
18d70 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
18d80 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
18d90 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
18da0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
18db0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
18dc0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
18dd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18de0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
18df0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
18e00 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
18e10 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
18e20 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
18e30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
18e40 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
18e50 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
18e60 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
18e70 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
18e80 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
18e90 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
18ea0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
18eb0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
18ec0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
18ed0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
18ee0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
18ef0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
18f00 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
18f10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18f20 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
18f30 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18f40 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
18f50 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18f60 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
18f70 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
18f80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
18f90 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
18fa0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
18fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18fc0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
18fd0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
18fe0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18ff0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
19000 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
19010 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
19020 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
19030 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
19040 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
19050 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19060 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
19070 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19080 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
19090 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
190a0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
190b0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
190c0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
190d0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
190e0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
190f0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
19100 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19110 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
19120 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
19130 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
19140 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
19150 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
19160 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
19170 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
19180 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
19190 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
191a0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
191b0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
191c0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
191d0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
191e0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
191f0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
19200 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
19210 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
19220 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19230 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
19240 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
19250 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
19260 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
19270 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
19280 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
19290 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
192a0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
192b0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
192c0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
192d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
192e0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
192f0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
19300 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
19310 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
19320 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
19330 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
19340 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
19350 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
19360 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
19370 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
19380 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
19390 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
193a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
193b0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
193c0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
193d0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
193e0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
193f0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
19400 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
19410 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
19420 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
19430 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
19440 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
19450 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
19460 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
19470 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
19480 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19490 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
194a0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
194b0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
194c0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
194d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
194e0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
194f0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
19500 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19510 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19520 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19530 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19540 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19550 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19560 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19570 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
19580 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
19590 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
195a0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
195b0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
195c0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
195d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
195e0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
195f0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19600 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19610 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19620 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
19630 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19640 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19650 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19660 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19670 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19680 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19690 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
196a0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
196b0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
196c0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
196d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
196e0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
196f0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
19700 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19710 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19720 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19730 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
19740 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19750 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
19760 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
19770 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19780 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
19790 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
197a0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
197b0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
197c0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
197d0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
197e0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
197f0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19800 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
19810 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19820 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19830 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19840 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19850 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19860 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19870 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
19880 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
19890 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
198a0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
198b0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
198c0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
198d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
198e0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
198f0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
19900 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19910 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
19920 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
19930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19940 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
19950 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
19960 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
19970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19980 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19990 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
199a0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
199b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
199c0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
199d0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
199e0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
199f0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
19a00 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
19a10 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
19a20 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
19a30 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19a40 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19a50 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19a60 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
19a70 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
19a80 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
19a90 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
19aa0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
19ab0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
19ac0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
19ad0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19ae0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19af0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19b00 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
19b10 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
19b20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74  CALL sqlite3_ext
19b30 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
19b40 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
19b50 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
19b60 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
19b70 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
19b80 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19b90 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
19ba0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
19bb0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
19bc0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
19bd0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
19be0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
19bf0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
19c00 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
19c10 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
19c20 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
19c30 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
19c40 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
19c50 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
19c60 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
19c70 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
19c80 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
19c90 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
19ca0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
19cb0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
19cc0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
19cd0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
19ce0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
19cf0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
19d00 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
19d10 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
19d20 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
19d30 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
19d40 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
19d50 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19d60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
19d70 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
19d80 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
19d90 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
19da0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
19db0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
19dc0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
19dd0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
19de0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
19df0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
19e00 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19e10 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
19e20 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
19e30 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19e40 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19e50 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
19e60 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
19e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19e80 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
19e90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
19ea0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19eb0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
19ec0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
19ed0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
19ee0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
19ef0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
19f00 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
19f10 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
19f20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
19f30 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
19f40 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
19f50 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
19f60 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
19f70 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
19f80 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
19f90 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
19fa0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
19fb0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
19fc0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
19fd0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
19fe0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
19ff0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
1a000 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
1a010 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
1a020 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
1a030 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
1a040 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1a050 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1a060 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1a070 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1a080 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1a090 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1a0a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1a0b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a0c0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1a0d0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1a0e0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1a0f0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1a100 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1a110 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1a120 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1a130 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1a140 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a150 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1a160 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1a170 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1a180 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1a190 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1a1a0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1a1b0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1a1c0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1a1d0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1a1e0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1a1f0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1a200 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1a210 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1a220 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1a230 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a240 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1a250 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1a260 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a270 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1a280 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1a290 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1a2a0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1a2b0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1a2c0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1a2d0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1a2e0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1a2f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1a300 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1a310 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1a320 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1a330 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1a340 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a350 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a360 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a370 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1a380 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1a390 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1a3a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1a3b0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1a3c0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1a3d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1a3e0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1a3f0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1a400 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1a410 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1a420 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1a430 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1a440 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a450 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1a460 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1a470 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1a480 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1a490 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1a4a0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1a4b0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
1a4c0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1a4d0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1a4e0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1a4f0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1a500 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a510 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
1a520 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1a530 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1a540 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a550 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1a560 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1a570 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1a580 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
1a590 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1a5a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1a5b0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
1a5c0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a5d0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1a5e0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
1a5f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
1a600 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
1a610 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
1a620 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1a630 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1a640 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
1a650 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
1a660 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1a670 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1a680 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
1a690 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
1a6a0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
1a6b0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a6c0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a6d0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
1a6e0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
1a6f0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1a700 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
1a710 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
1a720 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1a730 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
1a740 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
1a750 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
1a760 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1a770 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
1a780 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a790 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
1a7a0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1a7b0 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
1a7c0 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
1a7d0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
1a7e0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
1a7f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1a800 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
1a810 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
1a820 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a830 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
1a840 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
1a850 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
1a860 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
1a870 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
1a880 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
1a890 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
1a8a0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
1a8b0 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
1a8c0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a8d0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
1a8e0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
1a8f0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a900 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
1a910 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
1a920 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
1a930 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
1a940 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
1a950 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
1a960 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
1a970 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
1a980 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a990 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
1a9a0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
1a9b0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
1a9c0 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
1a9d0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a9e0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
1a9f0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1aa00 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
1aa10 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
1aa20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
1aa30 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1aa40 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
1aa50 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
1aa60 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
1aa70 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
1aa80 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
1aa90 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
1aaa0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
1aab0 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
1aac0 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
1aad0 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
1aae0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1aaf0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1ab00 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1ab10 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
1ab20 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
1ab30 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
1ab40 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
1ab50 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
1ab60 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
1ab70 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
1ab80 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
1ab90 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1aba0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
1abb0 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
1abc0 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
1abd0 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
1abe0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
1abf0 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
1ac00 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
1ac10 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
1ac20 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
1ac30 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
1ac40 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
1ac50 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1ac60 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1ac70 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1ac80 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
1ac90 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
1aca0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
1acb0 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
1acc0 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
1acd0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
1ace0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1acf0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
1ad00 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
1ad10 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
1ad20 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
1ad30 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
1ad40 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
1ad50 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1ad60 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
1ad70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
1ad80 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1ad90 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1ada0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
1adb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
1adc0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1add0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1ade0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1adf0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1ae00 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1ae10 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1ae20 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1ae30 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1ae40 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1ae50 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1ae60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ae70 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1ae80 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ae90 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1aea0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1aeb0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1aec0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1aed0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1aee0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1aef0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1af00 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1af10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1af20 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1af30 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1af40 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1af50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1af60 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1af70 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
1af80 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
1af90 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
1afa0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
1afb0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
1afc0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
1afd0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1afe0 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
1aff0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
1b000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1b010 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
1b020 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
1b030 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
1b040 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
1b050 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
1b060 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1b070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1b080 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
1b090 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1b0a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1b0b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
1b0c0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
1b0d0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1b0e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1b0f0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
1b100 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
1b110 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
1b120 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
1b130 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
1b140 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1b150 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
1b160 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1b170 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1b180 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
1b190 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
1b1a0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1b1b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b1c0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1b1d0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b1e0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b1f0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b200 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1b210 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b220 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b230 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b240 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b250 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b270 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b280 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b290 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1b2a0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1b2b0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1b2c0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1b2d0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1b2e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b2f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1b300 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b310 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1b320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b330 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1b340 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1b350 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b360 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1b370 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1b380 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1b390 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1b3a0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1b3b0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1b3c0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1b3d0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1b3e0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1b3f0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1b400 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1b410 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1b420 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1b430 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1b440 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1b450 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1b460 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1b470 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1b480 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1b490 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1b4a0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1b4b0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1b4c0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1b4d0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1b4e0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1b4f0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1b500 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1b510 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1b520 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b530 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1b540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1b550 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1b560 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1b570 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1b580 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1b590 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1b5a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1b5b0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1b5c0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1b5d0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1b5e0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1b5f0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1b600 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1b610 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1b620 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1b630 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1b640 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1b650 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1b660 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1b670 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1b680 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1b690 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1b6a0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1b6b0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1b6c0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1b6d0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1b6e0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1b6f0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1b700 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1b710 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1b720 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1b730 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1b740 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1b750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b760 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1b770 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1b780 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1b790 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1b7a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1b7b0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1b7c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1b7d0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1b7e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b7f0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b800 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1b810 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b820 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1b830 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1b840 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1b850 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1b860 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1b870 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1b880 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1b890 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1b8a0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1b8b0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1b8c0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1b8d0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1b8e0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1b8f0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1b900 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1b910 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1b920 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b930 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1b940 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1b950 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1b960 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1b970 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1b980 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b990 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1b9a0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1b9b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1b9c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b9d0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b9e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b9f0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1ba00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1ba10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ba20 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1ba30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ba40 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1ba50 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1ba60 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1ba70 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1ba80 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1ba90 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1baa0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1bab0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1bac0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1bad0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1bae0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1baf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1bb00 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1bb10 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1bb20 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1bb30 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1bb40 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1bb50 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1bb60 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1bb70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1bb80 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1bb90 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1bba0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1bbb0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1bbc0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1bbd0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1bbe0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bbf0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1bc00 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1bc10 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1bc20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1bc30 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1bc40 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1bc50 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1bc60 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1bc70 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1bc80 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1bc90 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1bca0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1bcb0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1bcc0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1bcd0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1bce0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1bcf0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1bd00 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1bd10 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1bd20 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1bd30 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1bd40 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1bd50 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1bd60 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1bd70 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1bd80 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1bd90 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1bda0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1bdb0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1bdc0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1bdd0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1bde0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1bdf0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1be00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1be10 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1be20 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1be30 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1be40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1be50 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1be60 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1be70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1be80 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1be90 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1bea0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1beb0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1bec0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1bed0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1bee0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1bef0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1bf00 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1bf10 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1bf20 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1bf30 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1bf40 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1bf50 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1bf60 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1bf70 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1bf80 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1bf90 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1bfa0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1bfb0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1bfc0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1bfd0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1bfe0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1bff0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1c000 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1c010 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1c020 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1c030 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1c040 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1c050 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1c060 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1c070 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c080 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1c090 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1c0a0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1c0b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1c0c0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1c0d0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1c0e0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1c0f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1c100 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1c110 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1c120 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c130 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1c140 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1c150 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1c160 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c170 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1c180 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1c190 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1c1a0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1c1b0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1c1c0 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
1c1d0 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
1c1e0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
1c1f0 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d  sy handler}.** M
1c200 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c210 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c220 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
1c230 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
1c240 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1c250 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
1c260 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1c270 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
1c280 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
1c290 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1c2a0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
1c2b0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
1c2c0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
1c2d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c2e0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
1c2f0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1c300 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
1c310 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
1c320 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
1c330 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
1c340 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
1c350 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
1c360 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1c370 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
1c380 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c390 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
1c3a0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1c3b0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1c3c0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
1c3d0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1c3e0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1c3f0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1c400 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1c410 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1c420 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1c430 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1c440 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1c450 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1c460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1c470 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1c480 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c490 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1c4a0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1c4b0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1c4c0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1c4d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c4e0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1c4f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1c500 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c510 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1c520 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1c530 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1c540 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1c550 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1c560 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1c570 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1c580 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1c590 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1c5a0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1c5b0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1c5c0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1c5d0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1c5e0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1c5f0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1c600 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1c610 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1c620 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1c630 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1c640 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1c650 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1c660 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1c670 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1c680 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1c690 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1c6a0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1c6b0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1c6c0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1c6d0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1c6e0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1c6f0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1c700 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1c710 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1c720 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1c730 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1c740 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1c750 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1c760 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1c770 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1c780 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1c790 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1c7a0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1c7b0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1c7c0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1c7d0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1c7e0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1c7f0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1c800 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1c810 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1c820 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1c830 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1c840 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1c850 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1c860 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1c870 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1c880 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1c890 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1c8a0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1c8b0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1c8c0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1c8d0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1c8e0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1c8f0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1c900 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1c910 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c920 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1c930 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1c940 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1c950 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c960 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1c970 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1c980 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1c990 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1c9a0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1c9b0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1c9c0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1c9d0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1c9e0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1c9f0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1ca00 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1ca10 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1ca20 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1ca30 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1ca40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1ca50 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1ca60 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1ca70 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1ca80 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1ca90 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1caa0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1cab0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cac0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1cad0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1cae0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1caf0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1cb00 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1cb10 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1cb20 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1cb30 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1cb40 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1cb50 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1cb60 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1cb70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1cb80 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1cb90 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1cba0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1cbb0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1cbc0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1cbd0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1cbe0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1cbf0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1cc00 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1cc10 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1cc20 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1cc30 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1cc40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1cc50 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1cc60 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1cc70 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1cc80 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1cc90 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1cca0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1ccb0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1ccc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1ccd0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1cce0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1ccf0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1cd00 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1cd10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1cd20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1cd30 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1cd40 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1cd50 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1cd60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cd70 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1cd80 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1cd90 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1cda0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1cdb0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1cdc0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1cdd0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1cde0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1cdf0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1ce00 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1ce10 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1ce20 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1ce30 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1ce40 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1ce50 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1ce60 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1ce70 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1ce80 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1ce90 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1cea0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1ceb0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1cec0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1ced0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1cee0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1cef0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1cf00 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1cf10 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1cf20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1cf30 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1cf40 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1cf50 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1cf60 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1cf70 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1cf80 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1cf90 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1cfa0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1cfb0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1cfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cfd0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1cfe0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1cff0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d000 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1d010 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1d020 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1d030 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1d040 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1d050 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1d060 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1d070 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1d080 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1d090 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1d0a0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
1d0b0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1d0c0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  LL sqlite3_busy_
1d0d0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1d0e0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1d0f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1d100 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1d110 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1d120 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1d130 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1d140 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1d150 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1d160 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1d170 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d180 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1d190 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1d1a0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1d1b0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1d1c0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1d1d0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1d1e0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1d1f0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1d200 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d210 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1d220 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1d230 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1d240 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1d250 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1d260 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1d270 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1d280 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1d290 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1d2a0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1d2b0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1d2c0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1d2d0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1d2e0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1d2f0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1d300 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1d310 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1d320 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1d330 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1d340 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1d350 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1d360 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1d370 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1d380 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1d390 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1d3a0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1d3b0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1d3c0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1d3d0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1d3e0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1d3f0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1d400 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1d410 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1d420 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1d430 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1d440 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1d450 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1d460 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1d470 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1d480 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1d490 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1d4a0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1d4b0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1d4c0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1d4d0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1d4e0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1d4f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1d500 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1d510 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1d520 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1d530 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1d540 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1d550 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1d560 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1d570 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1d580 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1d590 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1d5a0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1d5b0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1d5c0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1d5d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d5e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1d5f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1d600 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d610 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1d620 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1d630 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1d640 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d650 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1d660 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1d670 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1d680 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d690 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1d6a0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1d6b0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1d6c0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1d6d0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1d6e0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1d6f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1d700 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1d710 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1d720 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1d730 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1d740 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1d750 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1d760 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1d770 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1d780 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1d790 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1d7a0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1d7b0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1d7c0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1d7d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d7e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d7f0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1d800 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d810 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1d820 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1d830 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1d840 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1d850 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d860 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1d870 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d880 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1d890 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d8a0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1d8b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d8c0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1d8d0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1d8e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1d8f0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1d900 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1d910 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1d920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d930 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1d940 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1d950 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1d960 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1d970 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1d980 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1d990 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1d9a0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1d9b0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1d9c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1d9d0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1d9e0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1d9f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1da00 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1da10 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1da20 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1da30 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1da40 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1da50 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1da60 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1da70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1da80 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1da90 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1daa0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1dab0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1dac0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1dad0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1dae0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1daf0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1db00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1db10 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1db20 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1db30 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1db40 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1db50 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1db60 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1db70 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1db80 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1db90 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1dba0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1dbb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1dbc0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1dbd0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1dbe0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1dbf0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1dc00 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1dc10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1dc20 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1dc30 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1dc40 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1dc50 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1dc60 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1dc70 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1dc80 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1dc90 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1dca0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1dcb0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1dcc0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1dcd0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1dce0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1dcf0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1dd00 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1dd10 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1dd20 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1dd30 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1dd40 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1dd50 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1dd60 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1dd70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1dd80 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1dd90 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1dda0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1ddb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1ddc0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1ddd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1dde0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1ddf0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1de00 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1de10 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1de20 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1de30 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1de40 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1de50 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1de60 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1de70 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1de80 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1de90 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1dea0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1deb0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1dec0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1ded0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1dee0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1def0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1df00 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
1df10 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  L sqlite3_free_t
1df20 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1df30 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1df40 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1df50 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1df60 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1df70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1df80 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1df90 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1dfa0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1dfb0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1dfc0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1dfd0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1dfe0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1dff0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1e000 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1e010 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1e020 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1e030 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1e040 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1e050 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1e060 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1e070 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1e080 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e090 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1e0a0 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1e0b0 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1e0c0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1e0d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1e0e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e0f0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1e100 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1e110 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1e120 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1e130 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1e140 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1e150 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1e160 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1e170 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1e180 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1e190 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1e1a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1e1b0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1e1c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1e1d0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1e1e0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1e1f0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1e200 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1e210 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1e220 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1e230 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1e240 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1e250 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1e260 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1e270 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1e280 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1e290 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1e2a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1e2b0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1e2c0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1e2d0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1e2e0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1e2f0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1e300 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1e310 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1e320 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1e330 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1e340 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1e350 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1e360 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1e370 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1e380 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1e390 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1e3a0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1e3b0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1e3c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1e3d0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1e3e0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1e3f0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1e400 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1e410 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1e420 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1e430 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1e440 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1e450 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1e460 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1e470 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1e480 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1e490 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1e4a0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1e4b0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1e4c0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1e4d0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1e4e0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1e4f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1e500 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1e510 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1e520 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1e530 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1e540 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1e550 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1e560 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1e570 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1e580 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1e590 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1e5a0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1e5b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1e5c0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1e5d0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1e5e0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1e5f0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1e600 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1e610 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1e620 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1e630 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1e640 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1e650 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1e660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e670 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1e680 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1e690 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1e6a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e6b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1e6c0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1e6d0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1e6e0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1e6f0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1e700 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1e710 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1e720 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1e730 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1e740 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1e750 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1e760 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1e770 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1e780 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1e790 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1e7a0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1e7b0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1e7c0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1e7d0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1e7e0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1e7f0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1e800 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1e810 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1e820 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1e830 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1e840 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1e850 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1e860 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1e870 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1e880 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1e890 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1e8a0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1e8b0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1e8c0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1e8d0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1e8e0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1e8f0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1e900 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1e910 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1e920 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1e930 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e940 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e950 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1e960 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1e970 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e980 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1e990 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1e9a0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1e9b0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1e9c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e9d0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e9e0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e9f0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1ea00 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1ea10 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1ea20 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1ea30 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1ea40 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1ea50 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1ea60 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ea70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1ea80 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1ea90 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1eaa0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1eab0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1eac0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1ead0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1eae0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1eaf0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1eb00 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1eb10 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1eb20 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1eb30 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1eb40 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1eb50 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1eb60 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1eb70 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1eb80 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1eb90 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1eba0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1ebb0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1ebc0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ebd0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1ebe0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1ebf0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1ec00 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1ec10 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ec20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1ec30 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1ec40 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1ec50 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1ec60 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1ec70 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1ec80 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1ec90 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1eca0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1ecb0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1ecc0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1ecd0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1ece0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1ecf0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1ed00 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1ed10 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1ed20 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1ed30 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1ed40 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1ed50 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1ed60 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1ed70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1ed80 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1ed90 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1eda0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1edb0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1edc0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1edd0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1ede0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1edf0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1ee00 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1ee10 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1ee20 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1ee30 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1ee40 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1ee50 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1ee60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1ee70 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1ee80 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1ee90 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1eea0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1eeb0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1eec0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1eed0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1eee0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1eef0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1ef00 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ef10 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1ef20 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1ef30 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1ef40 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1ef50 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1ef60 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1ef70 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1ef80 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1ef90 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1efa0 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1efb0 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1efc0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1efd0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1efe0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1eff0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1f000 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1f010 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1f020 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1f030 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1f040 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1f050 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1f060 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1f070 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1f080 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1f090 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1f0a0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1f0b0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1f0c0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1f0d0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1f0e0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1f0f0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1f100 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1f110 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1f120 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
1f130 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1f140 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d  _CDECL sqlite3_m
1f150 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f160 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1f170 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1f180 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1f190 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1f1a0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f1b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1f1c0 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73   *SQLITE_CDECL s
1f1d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1f1e0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1f1f0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1f200 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1f210 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1f220 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1f230 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1f240 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1f250 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f260 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1f270 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1f280 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1f290 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1f2a0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1f2b0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1f2c0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1f2d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1f2e0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1f2f0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1f300 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1f310 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1f320 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1f330 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1f340 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1f350 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1f360 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1f370 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1f380 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1f390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f3a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1f3b0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1f3c0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1f3d0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1f3e0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1f3f0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1f400 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1f410 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1f420 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1f430 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1f440 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1f450 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1f460 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1f470 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1f480 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1f490 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f4a0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1f4b0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1f4c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1f4d0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1f4e0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1f4f0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1f500 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1f510 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1f520 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f530 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1f540 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1f550 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1f560 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1f570 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1f580 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1f590 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1f5a0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1f5b0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1f5c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1f5d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1f5e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f5f0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1f600 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1f610 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1f620 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1f630 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1f640 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1f650 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1f660 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1f670 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1f680 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1f690 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1f6a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1f6b0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1f6c0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1f6d0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1f6e0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1f6f0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1f700 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1f710 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1f720 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1f730 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1f740 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1f750 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1f760 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1f770 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1f780 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1f790 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1f7a0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1f7b0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1f7c0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1f7d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1f7e0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1f7f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1f800 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1f810 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1f820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f830 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f840 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1f850 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1f860 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1f870 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1f880 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1f890 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1f8a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f8b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f8c0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1f8d0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1f8e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1f8f0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1f900 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1f910 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1f920 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1f930 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1f940 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1f950 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1f960 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1f970 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1f980 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1f990 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1f9a0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1f9b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1f9c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f9d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1f9e0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1f9f0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1fa00 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1fa10 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1fa20 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1fa30 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1fa40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1fa50 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1fa60 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1fa70 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1fa80 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1fa90 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1faa0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1fab0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1fac0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1fad0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1fae0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1faf0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1fb00 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1fb10 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1fb20 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1fb30 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1fb40 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1fb50 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1fb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1fb70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1fb80 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1fb90 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1fba0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1fbb0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1fbc0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1fbd0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1fbe0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1fbf0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1fc00 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1fc10 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1fc20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fc30 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1fc40 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1fc50 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1fc60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1fc70 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1fc80 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1fc90 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1fca0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1fcb0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1fcc0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1fcd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fce0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1fcf0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1fd00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1fd10 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1fd20 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1fd30 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1fd40 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1fd50 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1fd60 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1fd70 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1fd80 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1fd90 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1fda0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1fdb0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1fdc0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1fdd0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1fde0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1fdf0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1fe00 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1fe10 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1fe20 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1fe30 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1fe40 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1fe50 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1fe60 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1fe70 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1fe80 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1fe90 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1fea0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1feb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1fec0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1fed0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1fee0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1fef0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1ff00 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1ff10 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1ff20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1ff30 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1ff40 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1ff50 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1ff60 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1ff70 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1ff80 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1ff90 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1ffa0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1ffb0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1ffc0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1ffd0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1ffe0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1fff0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
20000 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
20010 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
20020 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
20030 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
20040 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
20050 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
20060 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
20070 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
20080 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20090 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
200a0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
200b0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
200c0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
200d0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
200e0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
200f0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
20100 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
20110 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
20120 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
20130 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
20140 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
20150 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
20160 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
20170 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
20180 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
20190 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
201a0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
201b0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
201c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
201d0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
201e0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
201f0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
20200 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
20210 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
20220 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
20230 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20240 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
20250 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
20260 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
20270 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
20280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20290 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
202a0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
202b0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
202c0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
202d0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
202e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
202f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
20300 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
20310 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
20320 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
20330 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
20340 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
20350 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
20360 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
20370 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
20380 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
20390 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
203a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
203b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
203c0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
203d0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
203e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
203f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
20400 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20410 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
20420 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
20430 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
20440 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
20450 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
20460 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  LL sqlite3_reall
20470 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
20480 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
20490 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
204a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
204b0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
204c0 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
204d0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
204e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
204f0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51  _free(void*);.SQ
20500 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
20510 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  _uint64 SQLITE_S
20520 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
20530 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
20540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
20550 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
20560 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
20570 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
20580 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
20590 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
205a0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
205b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
205c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
205d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
205e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
205f0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
20600 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
20610 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
20620 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20630 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
20640 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20650 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
20660 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
20670 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
20680 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
20690 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
206a0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
206b0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
206c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
206d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
206e0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
206f0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
20700 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
20710 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20720 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
20730 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
20740 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
20750 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
20760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20770 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20780 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
20790 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
207a0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
207b0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
207c0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
207d0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
207e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
207f0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
20800 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
20810 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
20820 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
20830 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
20840 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
20850 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
20860 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
20870 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
20880 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
20890 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
208a0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
208b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
208c0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
208d0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
208e0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
208f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20900 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
20910 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
20920 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
20930 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20940 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
20950 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
20960 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
20970 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
20980 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
20990 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
209a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
209b0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
209c0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
209d0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
209e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
209f0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
20a00 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
20a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
20a20 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
20a30 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20a40 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20a50 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20a60 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
20a70 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
20a80 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
20a90 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
20aa0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
20ab0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
20ac0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
20ad0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
20ae0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
20af0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
20b00 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
20b10 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
20b20 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
20b30 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
20b40 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
20b50 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
20b60 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
20b70 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
20b80 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
20b90 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
20ba0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
20bb0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
20bc0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20bd0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
20be0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
20bf0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
20c00 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
20c10 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
20c20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20c30 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
20c40 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
20c50 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
20c60 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
20c70 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
20c80 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
20c90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20ca0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
20cb0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
20cc0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
20cd0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
20ce0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
20cf0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
20d00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20d10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
20d20 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
20d30 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
20d40 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
20d50 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
20d60 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
20d70 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
20d80 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
20d90 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
20da0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
20db0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
20dc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
20dd0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
20de0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
20df0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
20e00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
20e10 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
20e20 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
20e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e40 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
20e50 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
20e60 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
20e70 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
20e80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
20e90 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
20ea0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
20eb0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
20ec0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
20ed0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
20ee0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
20ef0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20f00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20f10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20f20 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
20f30 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
20f40 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
20f50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20f60 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
20f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20f80 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
20f90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
20fa0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
20fb0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
20fc0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
20fd0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
20fe0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
20ff0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
21000 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
21010 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
21020 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
21030 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21040 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21050 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
21060 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
21070 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
21080 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21090 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
210a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
210b0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
210c0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
210d0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
210e0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
210f0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
21100 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
21110 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
21120 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
21130 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
21140 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
21150 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
21160 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
21170 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
21180 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
21190 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
211a0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
211b0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
211c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
211d0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
211e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
211f0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
21200 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21210 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
21220 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
21230 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
21240 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
21250 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
21260 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
21270 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
21280 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21290 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
212a0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
212b0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
212c0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
212d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
212e0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
212f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21300 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21310 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
21320 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
21330 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21340 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
21350 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21360 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
21370 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
21380 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
21390 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
213a0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
213b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
213c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
213d0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
213e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
213f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21400 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
21410 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
21420 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
21430 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21440 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
21450 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
21460 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
21470 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
21480 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
21490 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
214a0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
214b0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
214c0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
214d0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
214e0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
214f0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
21500 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
21510 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
21520 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
21530 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
21540 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21550 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
21560 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
21570 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
21580 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
21590 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
215a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
215b0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
215c0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
215d0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
215e0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
215f0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
21600 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
21610 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
21620 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
21630 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
21640 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
21650 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
21660 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
21670 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
21680 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
21690 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
216a0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
216b0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
216c0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
216d0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
216e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
216f0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
21700 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
21710 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
21720 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
21730 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
21740 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
21750 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
21760 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
21770 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
21780 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
21790 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
217a0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
217b0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
217c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
217d0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
217e0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
217f0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
21800 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
21810 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
21820 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
21830 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
21840 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
21850 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
21860 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
21870 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
21880 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
21890 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
218a0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
218b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
218c0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
218d0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
218e0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
218f0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
21900 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
21910 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
21920 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
21930 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
21940 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
21950 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
21960 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
21970 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
21980 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
21990 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
219a0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
219b0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
219c0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
219d0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
219e0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
219f0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
21a00 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
21a10 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
21a20 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
21a30 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
21a40 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
21a50 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
21a60 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
21a70 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
21a80 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
21a90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
21aa0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
21ab0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
21ac0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
21ad0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21ae0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
21af0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
21b00 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
21b10 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
21b20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
21b30 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
21b40 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
21b50 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
21b60 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
21b70 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
21b80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
21b90 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
21ba0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
21bb0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
21bc0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
21bd0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
21be0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
21bf0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
21c00 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
21c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
21c20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21c30 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
21c40 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
21c50 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
21c60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21c70 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
21c80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21c90 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
21ca0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
21cb0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21cd0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21ce0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21cf0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
21d00 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
21d10 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
21d20 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
21d30 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
21d40 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
21d50 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
21d60 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
21d70 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
21d80 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
21d90 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
21da0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
21db0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
21dc0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
21dd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
21de0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
21df0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
21e00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21e10 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
21e20 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
21e30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e40 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
21e50 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
21e60 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
21e70 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
21e80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
21e90 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
21ea0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
21eb0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
21ec0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
21ed0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
21ee0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
21ef0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
21f00 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
21f10 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
21f20 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
21f30 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
21f40 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
21f50 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
21f60 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
21f70 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
21f80 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
21f90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
21fa0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
21fb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21fc0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21fd0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21fe0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
21ff0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
22000 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
22010 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
22020 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
22030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22040 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
22050 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
22060 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
22070 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
22080 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22090 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
220a0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
220b0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
220c0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
220d0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
220e0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
220f0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
22100 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
22110 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
22120 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
22130 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22140 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
22150 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
22160 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
22170 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
22180 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
22190 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
221a0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
221b0 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
221c0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
221d0 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
221e0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
221f0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
22200 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
22210 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
22220 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
22230 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22240 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
22250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22260 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
22270 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
22280 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
22290 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
222a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
222b0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
222c0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
222d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
222e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
222f0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
22300 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
22310 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
22320 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
22330 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
22340 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
22350 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
22360 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
22370 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
22380 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
22390 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
223a0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
223b0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
223c0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
223d0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
223e0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
223f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22400 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
22410 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
22420 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
22430 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
22440 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
22450 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
22460 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
22470 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
22480 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
22490 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
224a0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
224b0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
224c0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
224d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
224e0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
224f0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
22500 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22510 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
22520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22530 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
22540 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
22550 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
22560 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
22570 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
22580 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
22590 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
225a0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
225b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
225c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
225d0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
225e0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
225f0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
22600 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
22610 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
22620 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
22630 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
22640 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
22650 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
22660 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
22670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22690 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
226a0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
226b0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
226c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
226d0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
226e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
226f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22710 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
22720 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
22730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22760 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
22770 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
22780 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
227a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
227c0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
227d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
227e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
227f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22800 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
22810 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
22820 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22850 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
22860 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
22870 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
228a0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
228b0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
228c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
228d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
228e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
228f0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
22900 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
22910 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
22940 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
22950 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
22960 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22970 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22990 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
229a0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
229b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
229c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
229e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
229f0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
22a00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22a20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22a30 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
22a40 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
22a50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22a60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22a70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22a80 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
22a90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22ac0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22ad0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
22ae0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22af0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22b20 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
22b30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22b40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b60 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
22b70 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
22b80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22b90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22bb0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
22bc0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
22bd0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c00 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
22c10 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
22c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22c30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c50 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
22c60 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
22c70 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
22c80 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
22c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ca0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
22cb0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
22cc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22cd0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22cf0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
22d00 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
22d10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
22d20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d40 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
22d50 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
22d60 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
22d70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
22d90 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
22da0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
22db0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22dc0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22de0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22df0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
22e00 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
22e10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
22e30 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22e40 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
22e50 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
22e60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
22e80 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
22e90 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
22ea0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
22eb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22ec0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22ed0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22ee0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22ef0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22f00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22f10 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
22f20 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
22f30 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22f40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22f50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22f60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22f70 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
22f80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22f90 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22fa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22fb0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22fc0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22fd0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22fe0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22ff0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23000 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
23010 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
23020 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
23030 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
23040 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
23050 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
23060 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
23070 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
23080 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
23090 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
230a0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
230b0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
230c0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
230d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
230e0 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
230f0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
23100 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23110 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23120 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
23130 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
23140 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
23150 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
23160 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
23170 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
23180 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
23190 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
231a0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
231b0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
231c0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
231d0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
231e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
231f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
23200 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
23210 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
23220 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
23230 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
23240 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
23250 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
23260 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
23270 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
23280 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23290 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
232a0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
232b0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
232c0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
232d0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
232e0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
232f0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
23300 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
23310 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
23320 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
23330 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
23340 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
23350 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
23360 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
23370 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
23380 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
23390 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
233a0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
233b0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
233c0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
233d0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
233e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
233f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
23400 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
23410 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
23420 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
23430 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
23440 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
23450 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
23460 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
23470 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
23480 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
23490 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
234a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
234b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
234c0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
234d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
234e0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
234f0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
23500 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
23510 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
23520 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
23530 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
23540 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
23550 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
23560 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
23570 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
23580 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
23590 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
235a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
235b0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
235c0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
235d0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
235e0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
235f0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
23600 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
23610 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
23620 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23630 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
23640 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
23650 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
23660 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
23670 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
23680 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
23690 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
236a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
236b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
236c0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
236d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
236e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
236f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
23700 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
23710 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
23720 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
23730 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
23740 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
23750 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
23760 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
23770 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49  ENTAL void *SQLI
23780 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
23790 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
237a0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
237b0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
237c0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
237d0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
237e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
237f0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
23800 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
23810 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
23820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23830 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23840 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23850 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23860 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23870 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
23880 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23890 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
238a0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
238b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
238c0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
238d0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
238e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
238f0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
23900 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
23910 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
23920 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
23930 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23940 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23950 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23960 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23970 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
23980 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23990 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
239a0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
239b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
239c0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
239d0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
239e0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
239f0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
23a00 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
23a10 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
23a20 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
23a30 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
23a40 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
23a50 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
23a60 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
23a70 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
23a80 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
23a90 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
23aa0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
23ab0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
23ac0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
23ad0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
23ae0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
23af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
23b00 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
23b10 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
23b20 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
23b30 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
23b40 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
23b50 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
23b60 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23b70 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
23b80 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
23b90 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
23ba0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
23bb0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
23bc0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
23bd0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
23be0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
23bf0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
23c00 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
23c10 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
23c20 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
23c30 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
23c40 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
23c50 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
23c60 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
23c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
23c80 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
23c90 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
23ca0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
23cb0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
23cc0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23cd0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
23ce0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
23cf0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
23d00 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
23d10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23d30 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
23d40 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
23d50 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
23d60 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
23d70 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
23d80 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
23d90 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
23da0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
23db0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23dc0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
23dd0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
23de0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
23df0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23e00 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
23e10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
23e20 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
23e30 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23e40 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23e50 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23e60 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23e70 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23e80 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
23e90 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
23ea0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
23eb0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23ec0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
23ed0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23ef0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23f00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23f10 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23f20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23f30 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23f50 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23f60 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23f70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23f80 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23f90 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23fa0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23fb0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23fc0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23fd0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23fe0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23ff0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
24000 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
24010 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
24020 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
24030 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
24040 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
24050 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24060 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
24070 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
24080 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
24090 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
240a0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
240b0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
240c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
240d0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
240e0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
240f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
24100 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
24110 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
24120 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
24130 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
24140 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
24150 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
24160 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
24170 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
24180 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
24190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
241a0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
241b0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
241c0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
241d0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
241e0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
241f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
24200 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
24210 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
24220 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
24230 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
24240 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
24250 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24260 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
24270 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
24280 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
24290 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
242a0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
242b0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
242c0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
242d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
242e0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
242f0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
24300 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
24310 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
24320 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
24330 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
24340 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
24350 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
24360 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
24370 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
24380 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
24390 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
243a0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
243b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
243c0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
243d0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
243e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
243f0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
24400 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
24410 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
24420 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
24430 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
24440 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
24450 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24460 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
24470 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
24480 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
24490 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
244a0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
244b0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
244c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
244d0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
244e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
244f0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
24500 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
24510 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
24520 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24530 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24540 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24550 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24560 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24570 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24580 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24590 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
245a0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
245b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
245c0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
245d0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
245e0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
245f0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
24600 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
24610 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
24620 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
24630 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24640 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24650 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24660 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24670 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24680 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24690 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
246a0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
246b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
246c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
246d0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
246e0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
246f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24700 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24710 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
24720 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
24730 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24740 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24750 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24760 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24770 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24780 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24790 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
247a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
247b0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
247c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
247d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
247e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
247f0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
24800 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
24810 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
24820 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
24830 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24840 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24850 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24860 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24870 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24880 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24890 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
248a0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
248b0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
248c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
248d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
248e0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
248f0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
24900 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
24910 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
24920 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
24930 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24940 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24950 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24960 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24970 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24980 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24990 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
249a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
249b0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
249c0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
249d0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
249e0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
249f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
24a00 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
24a10 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24a20 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
24a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24a40 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24a50 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24a70 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
24a80 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
24a90 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
24aa0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24ab0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
24ac0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
24ad0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
24ae0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
24af0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
24b00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24b10 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
24b20 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24b40 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24b50 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24b60 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24b70 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
24b80 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24b90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24ba0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24bb0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
24bc0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
24bd0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
24be0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
24bf0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24c00 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24c10 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
24c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24c30 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24c40 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24c50 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24c60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24c70 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
24c80 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24c90 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
24ca0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24cb0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
24cc0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
24cd0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
24ce0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
24cf0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
24d00 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
24d10 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
24d20 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24d30 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24d40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24d50 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24d60 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24d70 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24d80 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24d90 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24da0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24db0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24dc0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
24dd0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
24de0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
24df0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24e00 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
24e10 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
24e20 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24e30 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24e40 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24e50 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24e60 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24e70 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24e80 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24e90 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24ea0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24eb0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24ec0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
24ed0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24ee0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24ef0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24f00 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24f10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24f20 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24f30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24f40 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24f50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24f60 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24f70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24f80 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24f90 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24fa0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24fb0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24fc0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24fd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24fe0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24ff0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
25000 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25010 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25020 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
25030 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
25040 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
25050 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
25060 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
25070 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
25080 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25090 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
250a0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
250b0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
250c0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
250d0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
250e0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
250f0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
25100 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
25110 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
25120 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
25130 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
25140 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
25150 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25160 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
25170 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
25180 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
25190 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
251a0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
251b0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
251c0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
251d0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
251e0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
251f0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
25200 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
25210 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
25220 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
25230 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
25240 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
25250 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
25260 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
25270 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
25280 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
25290 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
252a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
252b0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
252c0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
252d0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
252e0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
252f0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
25300 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
25310 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
25320 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
25330 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
25340 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
25350 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
25360 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
25370 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
25380 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
25390 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
253a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
253b0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
253c0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
253d0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
253e0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
253f0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
25400 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
25410 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25420 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
25430 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
25440 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
25450 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25460 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
25470 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
25480 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
25490 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
254a0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
254b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
254c0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
254d0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
254e0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
254f0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
25500 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
25510 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
25520 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
25530 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
25540 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
25550 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
25560 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25570 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
25580 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
25590 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
255a0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
255b0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
255c0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
255d0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
255e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
255f0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
25600 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
25610 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
25620 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
25630 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
25640 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
25650 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
25660 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
25670 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
25680 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
25690 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
256a0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
256b0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
256c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
256d0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
256e0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
256f0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
25700 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
25710 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
25720 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
25730 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
25740 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
25750 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
25760 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
25770 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
25780 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
25790 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
257a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
257b0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
257c0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
257d0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
257e0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
257f0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
25800 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
25810 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
25820 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
25830 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
25840 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25850 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25860 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
25870 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
25880 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25890 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
258a0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
258b0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
258c0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
258d0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
258e0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
258f0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
25900 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
25910 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
25920 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
25930 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25940 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
25950 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
25960 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
25970 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25980 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
25990 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
259a0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
259b0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
259c0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
259d0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
259e0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
259f0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
25a00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25a10 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
25a20 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
25a30 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
25a40 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
25a50 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
25a60 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
25a70 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
25a80 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
25a90 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
25aa0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
25ab0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
25ac0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25ad0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
25ae0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25af0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
25b00 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25b10 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
25b20 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
25b30 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25b40 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
25b50 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
25b60 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
25b70 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
25b80 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
25b90 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
25ba0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
25bb0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
25bc0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
25bd0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
25be0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
25bf0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
25c00 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
25c10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25c20 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25c30 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
25c40 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
25c50 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
25c60 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25c70 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
25c80 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
25c90 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
25ca0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
25cb0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25cc0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
25cd0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25ce0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
25cf0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
25d00 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
25d10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25d20 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
25d30 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25d40 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
25d50 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
25d60 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
25d70 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
25d80 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
25d90 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
25da0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25db0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
25dc0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
25dd0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
25de0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
25df0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
25e00 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
25e10 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
25e20 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25e30 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25e40 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25e50 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25e60 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
25e70 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
25e80 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
25e90 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
25ea0 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
25eb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
25ec0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
25ed0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
25ee0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
25ef0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
25f00 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
25f10 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
25f20 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
25f30 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25f40 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
25f50 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
25f60 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25f70 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
25f80 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
25f90 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
25fa0 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
25fb0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
25fc0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
25fd0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
25fe0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
25ff0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
26000 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
26010 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
26020 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
26030 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
26040 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
26050 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
26060 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
26070 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
26080 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
26090 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
260a0 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
260b0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
260c0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
260d0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
260e0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
260f0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
26100 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
26110 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
26120 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
26130 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
26140 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
26150 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
26160 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
26170 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
26180 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
26190 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
261a0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
261b0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
261c0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
261d0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
261e0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
261f0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
26200 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26210 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
26220 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
26230 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
26240 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
26250 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
26260 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
26270 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
26280 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
26290 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
262a0 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
262b0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
262c0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
262d0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
262e0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
262f0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
26300 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
26310 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
26320 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
26330 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
26340 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
26350 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
26360 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
26370 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
26380 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
26390 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
263a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
263b0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
263c0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
263d0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
263e0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
263f0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
26400 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
26410 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
26420 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
26430 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
26440 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
26450 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
26460 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
26470 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
26480 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
26490 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
264a0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
264b0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
264c0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
264d0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
264e0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
264f0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26500 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
26510 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
26520 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
26530 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
26540 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26550 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
26560 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26570 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26580 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
26590 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
265a0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
265b0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
265c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
265d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
265e0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
265f0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
26600 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
26610 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
26620 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
26630 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26640 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
26650 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
26660 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
26670 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
26680 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
26690 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
266a0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
266b0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
266c0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
266d0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
266e0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
266f0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
26700 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
26710 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
26720 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
26730 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
26740 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
26750 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
26760 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
26770 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
26780 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
26790 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
267a0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
267b0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
267c0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
267d0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
267e0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
267f0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
26800 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
26810 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
26820 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
26830 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
26840 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
26850 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
26860 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
26870 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26880 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
26890 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
268a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
268b0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
268c0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
268d0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
268e0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
268f0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
26900 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
26910 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
26920 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
26930 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
26940 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
26950 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
26960 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
26970 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
26980 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
26990 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
269a0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
269b0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
269c0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
269d0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
269e0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
269f0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
26a00 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
26a10 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
26a20 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
26a30 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26a40 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
26a50 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
26a60 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
26a70 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
26a80 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
26a90 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
26aa0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
26ab0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
26ac0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
26ad0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
26ae0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
26af0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
26b00 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
26b10 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
26b20 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
26b30 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
26b40 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
26b50 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
26b60 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
26b70 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
26b80 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
26b90 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
26ba0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
26bb0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
26bc0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
26bd0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
26be0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
26bf0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
26c00 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
26c10 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
26c20 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
26c30 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26c40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
26c50 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
26c60 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
26c70 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
26c80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26c90 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
26ca0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26cb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
26cc0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
26cd0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
26ce0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
26cf0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
26d00 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
26d10 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
26d20 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
26d30 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26d40 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
26d50 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
26d60 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
26d70 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26d80 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
26d90 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26da0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
26db0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
26dc0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
26dd0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
26de0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
26df0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
26e00 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26e10 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
26e20 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
26e30 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
26e40 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
26e50 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
26e60 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
26e70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26e80 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
26e90 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
26ea0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
26eb0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  LL sqlite3_open(
26ec0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26ed0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26ee0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26ef0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26f00 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26f10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26f20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26f30 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26f40 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
26f50 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  L sqlite3_open16
26f60 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
26f70 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26f80 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26f90 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
26fa0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
26fb0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
26fc0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
26fd0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26fe0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
26ff0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
27000 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
27010 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
27020 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
27030 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
27040 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
27050 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
27060 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
27070 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
27080 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27090 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
270a0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
270b0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
270c0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
270d0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
270e0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
270f0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
27100 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
27110 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
27120 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
27130 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
27140 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
27150 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
27160 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
27170 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
27180 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
27190 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
271a0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
271b0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
271c0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
271d0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
271e0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
271f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27200 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
27210 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27220 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
27230 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
27240 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
27250 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
27260 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
27270 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
27280 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
27290 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
272a0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
272b0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
272c0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
272d0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
272e0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
272f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
27300 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
27310 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27320 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
27330 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
27340 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
27350 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
27360 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
27370 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27380 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
27390 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
273a0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
273b0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
273c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
273d0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
273e0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
273f0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
27400 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
27410 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27420 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27430 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
27440 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
27450 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
27460 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
27470 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
27480 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
27490 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
274a0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
274b0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
274c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
274d0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
274e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
274f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27500 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
27510 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
27520 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
27530 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27540 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27550 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27560 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
27570 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27580 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
27590 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
275a0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
275b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
275c0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
275d0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
275e0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
275f0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
27600 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27610 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
27620 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
27630 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27640 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27650 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27660 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
27670 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
27680 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27690 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
276a0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
276b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
276c0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
276d0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
276e0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
276f0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
27700 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27710 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
27720 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
27730 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27740 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27750 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27760 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27770 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
27780 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
27790 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
277a0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
277b0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
277c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
277d0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
277e0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
277f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27800 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
27810 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
27820 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
27830 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27840 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27850 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27860 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27870 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27880 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
27890 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
278a0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
278b0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
278c0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
278d0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
278e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
278f0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
27900 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
27910 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
27920 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
27930 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
27940 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
27950 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
27960 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
27970 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
27980 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
27990 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
279a0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
279b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
279c0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
279d0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
279e0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
279f0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
27a00 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
27a10 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
27a20 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
27a30 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
27a40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
27a50 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
27a60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
27a70 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
27a80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
27a90 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
27aa0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
27ab0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
27ac0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
27ad0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
27ae0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
27af0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
27b00 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
27b10 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
27b20 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
27b30 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
27b40 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
27b50 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
27b60 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
27b70 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
27b80 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
27b90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
27ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
27bb0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
27bc0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
27bd0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
27be0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
27bf0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
27c00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27c10 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
27c20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27c30 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
27c40 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
27c50 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
27c60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
27c70 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
27c80 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
27c90 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
27ca0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
27cb0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
27cc0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
27cd0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
27ce0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
27cf0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
27d00 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
27d10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
27d20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
27d30 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
27d40 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
27d50 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
27d60 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
27d70 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
27d80 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
27d90 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
27da0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
27db0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
27dc0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
27dd0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
27de0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
27df0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
27e00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27e10 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
27e20 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
27e30 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27e40 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
27e50 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
27e60 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27e70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27e80 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27e90 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
27ea0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
27eb0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
27ec0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
27ed0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
27ee0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
27ef0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
27f00 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
27f10 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
27f20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
27f30 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
27f40 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
27f50 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
27f60 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
27f70 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
27f80 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
27f90 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
27fa0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
27fb0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
27fc0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
27fd0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
27fe0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
27ff0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
28000 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
28010 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
28020 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
28030 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
28040 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
28050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28060 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
28070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
28080 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
28090 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
280a0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
280b0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
280c0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
280d0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
280e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
280f0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
28100 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
28110 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
28120 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
28130 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
28140 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
28150 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
28160 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
28170 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
28180 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
28190 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
281a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
281b0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
281c0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
281d0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
281e0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
281f0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
28200 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
28210 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63  ALL sqlite3_errc
28220 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
28230 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28240 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28250 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
28260 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28270 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
28280 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
28290 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
282a0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
282b0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
282c0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
282d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
282e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
282f0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
28300 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
28310 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
28320 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
28330 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28340 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
28350 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
28360 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28370 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28380 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28390 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
283a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
283b0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
283c0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
283d0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
283e0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
283f0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
28400 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
28410 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
28420 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
28430 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
28440 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
28450 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
28460 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
28470 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
28480 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
28490 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
284a0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
284b0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
284c0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
284d0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
284e0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
284f0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28500 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28510 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28520 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28530 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28540 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28550 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28560 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28570 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
28580 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28590 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
285a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
285b0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
285c0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
285d0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
285e0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
285f0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28600 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28610 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28620 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28640 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28650 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28660 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28670 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28680 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28690 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
286a0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
286b0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
286c0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
286d0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
286e0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
286f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28700 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28710 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28720 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28730 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28740 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28750 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28760 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28770 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
28780 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
28790 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
287a0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
287b0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
287c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
287d0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
287e0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
287f0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28800 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28810 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28820 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28830 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28840 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28850 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28860 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28870 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28880 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
28890 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
288a0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
288b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
288c0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
288d0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
288e0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
288f0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28900 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28910 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28920 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28930 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28940 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28960 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
28970 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
28980 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
28990 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
289a0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
289b0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
289c0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
289d0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
289e0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
289f0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
28a00 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
28a10 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
28a20 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
28a30 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
28a40 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
28a50 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
28a60 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
28a70 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
28a80 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
28a90 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
28aa0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
28ab0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
28ac0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
28ad0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
28ae0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
28af0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28b00 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
28b10 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
28b20 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
28b30 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
28b40 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
28b50 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
28b60 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
28b70 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
28b80 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
28b90 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
28ba0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
28bb0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
28bc0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
28bd0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
28be0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
28bf0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
28c00 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
28c10 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
28c20 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
28c30 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
28c40 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
28c50 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
28c60 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
28c70 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
28c80 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
28c90 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
28ca0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
28cb0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
28cc0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
28cd0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
28ce0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
28cf0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
28d00 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
28d10 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
28d20 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28d30 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
28d40 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
28d50 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
28d60 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
28d70 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
28d80 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
28d90 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
28da0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
28db0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
28dc0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
28dd0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
28de0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
28df0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
28e00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
28e10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
28e20 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
28e30 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
28e40 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
28e50 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
28e60 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
28e70 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
28e80 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
28e90 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
28ea0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
28eb0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
28ec0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
28ed0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
28ee0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
28ef0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
28f00 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
28f10 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28f20 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28f30 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
28f40 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
28f50 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
28f60 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
28f70 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
28f80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
28f90 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
28fa0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
28fb0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
28fc0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
28fd0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
28fe0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
28ff0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
29000 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
29010 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
29020 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
29030 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
29040 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
29050 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
29060 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
29070 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
29080 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
29090 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
290a0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
290b0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
290c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
290d0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
290e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
290f0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
29100 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
29110 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
29120 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
29130 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
29140 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29150 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29160 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
29170 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29180 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
29190 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
291a0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
291b0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
291c0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
291d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
291e0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
291f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
29200 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
29210 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29220 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29230 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
29240 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
29250 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
29260 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
29270 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29280 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
29290 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
292a0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
292b0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
292c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
292d0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
292e0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
292f0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
29300 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
29310 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
29320 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
29330 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
29340 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
29350 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29360 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
29370 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
29380 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29390 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
293a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
293b0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
293c0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
293d0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
293e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
293f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
29400 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
29410 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
29420 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
29430 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29440 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
29450 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
29460 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
29470 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
29480 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
29490 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
294a0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
294b0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
294c0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
294d0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
294e0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
294f0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
29500 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29510 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29520 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
29530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29540 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
29550 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29560 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
29570 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
29580 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
29590 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
295a0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
295b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
295c0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
295d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
295e0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
295f0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
29600 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
29610 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29620 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29630 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
29640 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29650 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29660 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
29670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
29680 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
29690 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
296a0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
296b0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
296c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
296d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
296e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
296f0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
29700 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29710 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
29720 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
29730 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
29740 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
29750 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29760 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
29770 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29780 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29790 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
297a0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
297b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
297c0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
297d0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
297e0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
297f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29800 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
29810 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29820 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29830 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
29840 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29850 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
29860 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
29870 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
29880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29890 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
298a0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
298b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
298c0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
298d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
298e0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
298f0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29900 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29910 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
29920 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
29930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29940 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
29950 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
29960 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29970 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
29980 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
29990 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
299a0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
299b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
299c0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
299d0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
299e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
299f0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
29a00 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
29a10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
29a20 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
29a30 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
29a40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29a50 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29a60 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
29a70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29a80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
29a90 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
29aa0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29ab0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
29ac0 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
29ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29ae0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29af0 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
29b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
29b10 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
29b20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
29b30 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
29b40 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
29b50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29b60 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
29b70 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
29b80 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
29b90 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
29ba0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
29bb0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
29bc0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
29bd0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
29be0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
29bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
29c00 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
29c10 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
29c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
29c30 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
29c40 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
29c50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29c60 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
29c70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
29c80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
29c90 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
29ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29cb0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
29cc0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
29cd0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
29ce0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
29cf0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
29d00 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
29d10 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
29d20 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
29d30 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
29d40 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
29d50 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29d60 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
29d70 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
29d80 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29d90 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
29da0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29db0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
29dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
29dd0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
29de0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29df0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
29e00 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
29e10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29e20 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
29e30 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
29e40 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29e50 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
29e60 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
29e70 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
29e80 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
29e90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
29ea0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
29eb0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
29ec0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
29ed0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
29ee0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
29ef0 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
29f00 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
29f10 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
29f20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
29f30 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
29f40 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
29f50 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
29f60 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
29f70 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
29f80 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
29f90 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
29fa0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
29fb0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
29fc0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
29fd0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
29fe0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
29ff0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
2a000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2a010 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
2a020 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
2a030 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
2a040 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2a050 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
2a060 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2a070 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
2a080 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
2a090 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
2a0a0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2a0b0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
2a0c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a0d0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
2a0e0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
2a0f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a100 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
2a110 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
2a120 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
2a130 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
2a140 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
2a150 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
2a160 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
2a170 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
2a180 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
2a190 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
2a1a0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
2a1b0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
2a1c0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
2a1d0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
2a1e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
2a1f0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2a200 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a210 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
2a220 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2a230 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
2a240 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
2a250 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
2a260 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
2a270 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
2a280 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
2a290 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
2a2a0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2a2b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2a2c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a2d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2a2e0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
2a2f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a300 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
2a310 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
2a320 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2a330 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
2a340 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2a350 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
2a360 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2a370 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2a380 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2a390 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2a3a0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2a3b0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2a3c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2a3d0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2a3e0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2a3f0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2a400 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2a410 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2a420 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2a430 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2a440 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2a450 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2a460 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2a470 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2a480 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2a490 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2a4a0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2a4b0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2a4c0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2a4d0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2a4e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2a4f0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2a500 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2a510 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2a520 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2a530 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2a540 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2a550 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2a560 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2a570 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2a580 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2a590 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2a5a0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2a5b0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2a5c0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2a5d0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2a5e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2a5f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a600 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2a610 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2a620 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2a630 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2a640 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2a650 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2a660 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2a670 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a680 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2a690 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2a6a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2a6b0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2a6c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2a6d0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2a6e0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2a6f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2a700 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2a710 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2a720 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2a730 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2a740 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2a750 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2a760 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2a770 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2a780 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2a790 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2a7a0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a7b0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2a7c0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2a7d0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2a7e0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2a7f0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2a800 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2a810 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2a820 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a830 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2a840 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2a850 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2a860 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2a870 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2a880 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2a890 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2a8a0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2a8b0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2a8c0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2a8d0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2a8e0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2a8f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2a900 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2a910 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2a920 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2a930 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2a940 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2a950 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2a960 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2a970 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2a980 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a990 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2a9a0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2a9b0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2a9c0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2a9d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2a9e0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2a9f0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2aa00 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2aa10 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2aa20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2aa30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2aa40 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
2aa50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2aa60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2aa70 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
2aa80 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2aa90 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2aaa0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2aab0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2aac0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2aad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2aae0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2aaf0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ab00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2ab10 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ab20 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2ab30 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ab40 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ab50 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ab60 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ab70 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2ab80 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ab90 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2aba0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2abb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2abc0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2abd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2abe0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2abf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ac00 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ac10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ac20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2ac30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ac40 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2ac50 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ac60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2ac70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ac80 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2ac90 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2aca0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2acb0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2acc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2acd0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2ace0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2acf0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ad00 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ad10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ad20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ad30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ad40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ad50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ad60 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ad70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ad80 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ad90 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ada0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2adb0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2adc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2add0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ade0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2adf0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ae00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ae10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ae20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2ae30 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2ae40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ae50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ae60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ae70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ae80 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ae90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2aea0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2aeb0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2aec0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2aed0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2aee0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2aef0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2af00 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2af10 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2af20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2af30 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2af40 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2af50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2af60 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2af70 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2af80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2af90 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2afa0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2afb0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2afc0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2afd0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2afe0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2aff0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2b000 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b010 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2b020 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2b030 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
2b040 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
2b050 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
2b060 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2b070 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
2b080 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b090 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
2b0a0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
2b0b0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
2b0c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b0d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2b0e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b0f0 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
2b100 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2b110 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b120 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2b130 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b140 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b150 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2b160 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2b170 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2b180 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2b190 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b1a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b1b0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2b1c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b1d0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2b1e0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2b1f0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2b200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2b210 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2b220 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2b230 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2b240 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2b250 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2b260 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b270 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b280 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2b290 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2b2a0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2b2b0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2b2c0 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2b2d0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2b2e0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2b2f0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2b300 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2b310 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2b320 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2b330 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2b340 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2b350 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2b360 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2b370 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2b380 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2b390 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2b3a0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2b3b0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2b3c0 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2b3d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2b3e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2b3f0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2b400 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2b410 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2b420 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2b430 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2b440 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b450 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2b460 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2b470 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2b480 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2b490 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2b4a0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2b4b0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2b4c0 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2b4d0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2b4e0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2b4f0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2b500 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2b510 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2b520 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2b530 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2b540 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2b550 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2b560 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2b570 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2b580 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2b590 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2b5a0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2b5b0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2b5c0 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2b5d0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2b5e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b5f0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2b600 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2b610 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2b620 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2b630 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2b640 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2b650 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2b660 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2b670 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2b680 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2b690 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2b6a0 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   disk..*/.SQLITE
2b6b0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b6c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b6d0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
2b6e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b6f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b700 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2b710 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2b720 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
2b730 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
2b740 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b750 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b760 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
2b770 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b780 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2b790 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
2b7a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b7b0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
2b7c0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
2b7d0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2b7e0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
2b7f0 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20  has neither run 
2b800 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72  to completion (r
2b810 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2b820 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73  TE_DONE] from [s
2b830 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29  qlite3_step(S)])
2b840 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73   nor.** been res
2b850 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
2b860 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
2b870 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b880 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
2b890 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
2b8a0 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
2b8b0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
2b8c0 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
2b8d0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
2b8e0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
2b8f0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
2b900 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2b910 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
2b920 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b930 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2b940 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
2b950 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2b960 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2b970 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
2b980 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
2b990 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
2b9a0 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
2b9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
2b9c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
2b9d0 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
2b9e0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
2b9f0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
2ba00 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
2ba10 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
2ba20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
2ba30 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
2ba40 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
2ba50 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
2ba60 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
2ba70 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
2ba80 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
2ba90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2baa0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2bab0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2bac0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2bad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bae0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2baf0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2bb00 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2bb10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2bb20 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2bb30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bb40 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2bb50 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2bb60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bb70 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2bb80 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2bb90 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2bba0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2bbb0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2bbc0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2bbd0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2bbe0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2bbf0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2bc00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bc10 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2bc20 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2bc30 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2bc40 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2bc50 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2bc60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2bc70 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2bc80 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2bc90 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2bca0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2bcb0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2bcc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bcd0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2bce0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2bcf0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2bd00 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2bd10 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2bd20 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2bd30 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2bd40 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2bd50 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2bd60 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2bd70 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2bd80 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2bd90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bda0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2bdb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2bdc0 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2bdd0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2bde0 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2bdf0 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2be00 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2be10 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2be20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2be30 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2be40 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2be50 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2be60 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2be70 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2be80 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2be90 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2bea0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2beb0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bec0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2bed0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2bee0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2bef0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bf00 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2bf10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2bf20 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2bf30 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2bf40 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2bf50 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2bf60 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2bf70 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2bf80 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2bf90 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2bfa0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2bfb0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2bfc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2bfd0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2bfe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2bff0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2c000 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2c010 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2c020 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2c030 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2c040 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c050 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2c060 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2c070 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2c080 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2c090 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2c0a0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2c0b0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2c0c0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2c0d0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2c0e0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2c0f0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2c100 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2c110 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c120 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2c130 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2c140 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2c150 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c160 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2c170 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2c180 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2c190 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2c1a0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c1b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c1c0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2c1d0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2c1e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2c1f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2c200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2c210 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2c220 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2c230 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c240 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2c250 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2c260 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
2c270 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
2c280 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2c290 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
2c2a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c2b0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2c2c0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2c2d0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2c2e0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2c2f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c300 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2c310 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2c320 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
2c330 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2c340 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2c350 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2c360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2c370 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2c380 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2c390 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2c3a0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2c3b0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2c3c0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2c3d0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2c3e0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2c3f0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2c400 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2c410 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c420 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2c430 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2c440 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c450 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2c460 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2c470 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2c480 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2c490 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2c4a0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2c4b0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2c4c0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2c4d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2c4e0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2c4f0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2c500 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2c510 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2c520 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2c530 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2c540 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2c550 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2c560 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2c570 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2c580 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2c590 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2c5a0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2c5b0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2c5c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2c5d0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2c5e0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2c5f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2c600 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2c610 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2c620 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2c630 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2c640 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2c650 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c660 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2c670 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2c680 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2c690 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c6a0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2c6b0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2c6c0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2c6d0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2c6e0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2c6f0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2c700 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2c710 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2c720 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2c730 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2c740 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2c750 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2c760 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2c770 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2c780 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2c790 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2c7a0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2c7b0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2c7c0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2c7d0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2c7e0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2c7f0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2c800 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2c810 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2c820 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2c830 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2c840 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2c850 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2c860 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2c870 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2c880 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2c890 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2c8a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2c8b0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2c8c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2c8d0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2c8e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2c8f0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2c900 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2c910 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2c920 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2c930 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2c940 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2c950 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2c960 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2c970 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2c980 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2c990 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2c9a0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2c9b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2c9c0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2c9d0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2c9e0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2c9f0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2ca00 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2ca10 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2ca20 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2ca30 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2ca40 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2ca50 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2ca60 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2ca70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ca80 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2ca90 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2caa0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2cab0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2cac0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2cad0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2cae0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2caf0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2cb00 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2cb10 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2cb20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2cb30 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2cb40 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2cb50 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2cb60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2cb70 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2cb80 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2cb90 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2cba0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2cbb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cbc0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2cbd0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2cbe0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2cbf0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2cc00 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2cc10 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2cc20 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2cc30 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2cc40 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2cc50 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2cc60 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2cc70 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2cc80 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2cc90 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2cca0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2ccb0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2ccc0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2ccd0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2cce0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2ccf0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2cd00 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2cd10 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2cd20 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2cd30 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2cd40 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2cd50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2cd60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2cd70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2cd80 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2cd90 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2cda0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2cdb0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2cdc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2cdd0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2cde0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2cdf0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2ce00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2ce10 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2ce20 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2ce30 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2ce40 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2ce50 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2ce60 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2ce70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2ce80 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2ce90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2cea0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2ceb0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2cec0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2ced0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2cee0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2cef0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2cf00 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2cf10 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2cf20 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2cf30 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2cf40 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2cf50 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2cf60 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2cf70 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2cf80 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2cf90 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2cfa0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cfb0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2cfc0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2cfd0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2cfe0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2cff0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2d000 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2d010 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2d020 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2d030 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2d040 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2d050 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2d060 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2d070 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2d080 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2d090 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2d0a0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2d0b0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2d0c0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2d0d0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2d0e0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2d0f0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2d100 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2d110 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2d120 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2d130 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2d140 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2d150 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2d160 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2d170 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2d180 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2d190 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2d1a0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2d1b0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2d1c0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2d1d0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2d1e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2d1f0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2d200 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2d210 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2d220 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2d230 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2d240 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2d250 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2d260 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2d270 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2d280 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d290 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2d2a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2d2b0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2d2c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d2d0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2d2e0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2d2f0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2d300 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2d310 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2d320 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2d330 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2d340 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2d350 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2d360 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2d370 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2d380 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2d390 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2d3a0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2d3b0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2d3c0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2d3d0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2d3e0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2d3f0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2d400 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2d410 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2d420 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2d430 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2d440 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2d450 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d460 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2d470 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2d480 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2d490 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2d4a0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2d4b0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2d4c0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2d4d0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2d4e0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2d4f0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2d500 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2d510 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2d520 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2d530 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2d540 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2d550 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2d560 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2d570 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2d580 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d590 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2d5a0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2d5b0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2d5c0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2d5d0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2d5e0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2d5f0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2d600 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2d610 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2d620 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2d630 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2d640 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2d650 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2d660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d670 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2d680 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2d690 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2d6a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2d6b0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2d6c0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2d6d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d6e0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2d6f0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2d700 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d710 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2d720 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2d730 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2d740 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d750 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2d760 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2d770 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2d780 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2d790 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2d7a0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2d7b0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2d7c0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2d7d0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2d7e0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2d7f0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2d800 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2d810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d820 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2d830 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2d840 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2d850 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2d860 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2d870 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2d880 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2d890 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2d8a0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2d8b0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2d8c0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2d8d0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2d8e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2d8f0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2d900 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2d910 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2d920 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2d930 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2d940 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2d950 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2d960 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2d970 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2d980 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2d990 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2d9a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2d9b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2d9c0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2d9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2d9e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2d9f0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2da00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2da10 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2da20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2da30 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2da40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2da50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2da60 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2da70 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2da80 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2da90 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2daa0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2dab0 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2dac0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2dad0 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2dae0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2daf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2db00 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2db10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2db20 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2db30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2db40 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2db50 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2db60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2db70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2db80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2db90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2dba0 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
2dbb0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2dbc0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2dbd0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2dbe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2dbf0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2dc00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2dc10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2dc20 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2dc30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2dc40 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2dc50 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2dc60 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2dc70 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2dc80 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2dc90 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2dca0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2dcb0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2dcc0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2dcd0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2dce0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2dcf0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2dd00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2dd10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2dd20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2dd30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2dd40 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2dd50 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2dd60 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2dd70 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2dd80 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2dd90 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2dda0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2ddb0 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ing);.SQLITE_API
2ddc0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2ddd0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2dde0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2ddf0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2de00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2de10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2de20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2de30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2de40 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2de50 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2de60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2de70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2de80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2de90 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2dea0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2deb0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2dec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2ded0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2dee0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2def0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2df00 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2df10 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2df20 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2df30 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2df40 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2df50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2df60 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2df70 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2df80 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2df90 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2dfa0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2dfb0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2dfc0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2dfd0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2dfe0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2dff0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2e000 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2e010 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2e020 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2e030 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2e040 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2e050 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e060 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2e070 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2e080 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2e090 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2e0a0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2e0b0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2e0c0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2e0d0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2e0e0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2e0f0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2e100 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2e110 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2e120 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2e130 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e140 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e150 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e170 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2e180 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2e190 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e1a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2e1b0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e1c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e1d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e1e0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2e1f0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e200 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2e210 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2e220 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e230 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e240 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e250 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2e260 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2e270 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2e280 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2e290 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2e2a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e2b0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2e2c0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2e2d0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2e2e0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2e2f0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2e300 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2e310 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2e320 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2e330 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2e340 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2e350 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2e360 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2e370 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2e380 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2e390 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2e3a0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2e3b0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2e3c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2e3d0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2e3e0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2e3f0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2e400 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2e410 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2e420 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2e430 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2e440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2e450 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2e460 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2e470 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2e480 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2e490 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2e4a0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2e4b0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2e4c0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2e4d0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2e4e0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2e4f0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2e500 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2e510 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2e520 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2e530 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2e540 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2e550 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2e560 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2e570 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e580 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2e590 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e5a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e5b0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e5c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e5d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e5e0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2e5f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e600 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e610 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2e620 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2e630 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2e640 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e650 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2e660 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2e670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2e680 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2e690 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2e6a0 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2e6b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e6c0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2e6d0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2e6e0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2e6f0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2e700 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2e710 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2e720 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2e730 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2e740 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2e750 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e760 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2e770 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2e780 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2e790 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2e7a0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2e7b0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2e7c0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2e7d0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2e7e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2e7f0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2e800 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2e810 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2e820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e830 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2e840 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e850 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e860 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e880 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2e890 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e8a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e8b0 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  ame()]..*/.SQLIT
2e8c0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e8d0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e8e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e8f0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2e900 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2e910 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2e920 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2e930 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2e940 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2e950 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2e960 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e970 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2e980 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2e990 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2e9a0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2e9b0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2e9c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e9d0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2e9e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e9f0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2ea00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2ea10 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2ea20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2ea30 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2ea40 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2ea50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65  CALL sqlite3_cle
2ea60 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2ea70 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2ea80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2ea90 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2eaa0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2eab0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2eac0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2ead0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2eae0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2eaf0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2eb00 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2eb10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eb20 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2eb30 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2eb40 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2eb50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2eb60 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2eb70 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2eb80 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2eb90 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2eba0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2ebb0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2ebc0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2ebd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2ebe0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2ebf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ec00 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2ec10 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2ec20 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2ec30 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2ec40 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ec50 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2ec60 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2ec70 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2ec80 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2ec90 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2eca0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2ecb0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2ecc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2ecd0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2ece0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ecf0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2ed00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2ed10 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2ed20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2ed30 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2ed40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ed50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2ed60 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2ed70 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2ed80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ed90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2eda0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2edb0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2edc0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2edd0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2ede0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2edf0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2ee00 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2ee10 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2ee20 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2ee30 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2ee40 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2ee50 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2ee60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ee70 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2ee80 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2ee90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2eea0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2eeb0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2eec0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2eed0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2eee0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2eef0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2ef00 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2ef10 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2ef20 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2ef30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ef40 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2ef50 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2ef60 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2ef70 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2ef80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2ef90 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2efa0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2efb0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2efc0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2efd0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2efe0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2eff0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2f000 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2f010 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f020 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2f030 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2f040 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f050 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2f060 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2f070 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2f080 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2f090 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2f0a0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2f0b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2f0c0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2f0d0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2f0e0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2f0f0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2f100 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2f110 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f120 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2f130 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2f140 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2f150 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2f160 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f170 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2f180 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f190 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2f1a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f1b0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2f1c0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2f1d0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2f1e0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2f1f0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f200 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2f210 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2f220 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2f230 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2f240 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2f250 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2f260 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2f270 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2f280 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2f290 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2f2a0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2f2b0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2f2c0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2f2d0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2f2e0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2f2f0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2f300 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2f310 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2f320 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2f330 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2f340 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2f350 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2f360 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2f370 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2f380 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2f390 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2f3a0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2f3b0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2f3c0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2f3d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f3e0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2f3f0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2f400 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2f410 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2f420 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2f430 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2f440 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2f450 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2f460 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2f470 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2f480 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2f490 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2f4a0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2f4b0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2f4c0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2f4d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2f4e0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2f4f0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2f500 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2f510 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2f520 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2f530 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2f540 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2f550 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2f560 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2f570 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2f580 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2f590 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2f5a0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2f5b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2f5c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2f5d0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2f5e0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2f5f0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2f600 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2f610 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2f620 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2f630 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2f640 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2f650 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2f660 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2f670 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2f680 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2f690 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2f6a0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2f6b0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2f6c0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2f6d0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2f6e0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2f6f0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2f700 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2f710 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2f720 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2f730 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2f740 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f750 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2f760 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2f770 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2f780 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2f790 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2f7a0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2f7b0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2f7c0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2f7d0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2f7e0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2f7f0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2f800 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2f810 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2f820 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2f830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2f840 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2f850 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f860 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f870 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f880 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f890 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f8a0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f8b0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2f8c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f8d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f8e0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2f8f0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2f900 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2f910 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2f920 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2f930 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2f940 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2f950 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f960 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2f970 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2f980 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2f990 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f9a0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2f9b0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2f9c0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2f9d0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2f9e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2f9f0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2fa00 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2fa10 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2fa20 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2fa30 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2fa40 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2fa50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2fa60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2fa70 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2fa80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2fa90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2faa0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2fab0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2fac0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2fad0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2fae0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2faf0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2fb00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2fb10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2fb20 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2fb30 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2fb40 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2fb50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2fb60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb70 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2fb80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2fb90 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fba0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2fbb0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2fbc0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2fbd0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2fbe0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2fbf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
2fc00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2fc10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2fc20 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2fc30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2fc40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2fc50 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2fc60 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2fc70 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2fc80 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2fc90 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2fca0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2fcb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2fcc0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2fcd0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2fce0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2fcf0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2fd00 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2fd10 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2fd20 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2fd30 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2fd40 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2fd50 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2fd60 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2fd70 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2fd80 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2fd90 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2fda0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2fdb0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2fdc0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2fdd0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2fde0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2fdf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2fe00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2fe10 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2fe20 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2fe30 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2fe40 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2fe50 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2fe60 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2fe70 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2fe80 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2fe90 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2fea0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2feb0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2fec0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2fed0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2fee0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2fef0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2ff00 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2ff10 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2ff20 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2ff30 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2ff40 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2ff50 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2ff60 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2ff70 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2ff80 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2ff90 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2ffa0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2ffb0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2ffc0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2ffd0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2ffe0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2fff0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
30000 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
30010 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
30020 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
30030 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
30040 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
30050 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
30060 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
30070 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
30080 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
30090 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
300a0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
300b0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
300c0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
300d0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
300e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
300f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
30100 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
30110 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
30120 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
30130 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
30140 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
30150 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
30160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
30170 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
30180 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
30190 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
301a0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
301b0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
301c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
301d0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
301e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
301f0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
30200 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
30210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
30220 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
30230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30240 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
30250 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
30260 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
30270 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
30280 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30290 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
302a0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
302b0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
302c0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
302d0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
302e0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
302f0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
30300 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
30310 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
30320 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
30330 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
30340 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
30350 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
30360 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
30370 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
30380 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
30390 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
303a0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
303b0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
303c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
303d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
303e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
303f0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
30400 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
30410 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
30420 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
30430 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
30440 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
30450 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30460 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
30470 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30480 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
30490 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
304a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
304b0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
304c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
304d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
304e0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
304f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
30500 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
30510 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
30520 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
30530 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
30540 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
30550 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
30560 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
30570 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
30580 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
30590 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
305a0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
305b0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
305c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
305d0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
305e0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
305f0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
30600 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
30610 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
30620 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
30630 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
30640 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30650 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
30660 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
30670 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
30680 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
30690 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
306a0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
306b0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
306c0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
306d0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
306e0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
306f0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
30700 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
30710 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
30720 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
30730 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
30740 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
30750 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
30760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
30770 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
30780 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
30790 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
307a0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
307b0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
307c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
307d0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
307e0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
307f0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
30800 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
30810 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
30820 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
30830 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
30840 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
30850 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
30860 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
30870 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
30880 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
30890 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
308a0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
308b0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
308c0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
308d0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
308e0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
308f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
30900 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
30910 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
30920 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
30930 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
30940 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
30950 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
30960 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
30970 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
30980 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
30990 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
309a0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
309b0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
309c0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
309d0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
309e0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
309f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
30a00 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
30a10 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
30a20 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
30a30 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
30a40 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
30a50 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
30a60 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
30a70 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
30a80 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
30a90 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
30aa0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
30ab0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
30ac0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
30ad0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30ae0 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
30af0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30b00 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
30b10 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
30b20 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
30b30 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
30b40 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
30b50 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30b60 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30b70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
30b80 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
30b90 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
30ba0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
30bb0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
30bc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
30bd0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
30be0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
30bf0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
30c00 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
30c10 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
30c20 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
30c30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
30c40 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
30c50 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
30c60 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
30c70 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
30c90 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
30ca0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
30cb0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
30cc0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
30cd0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
30ce0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
30cf0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
30d00 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
30d10 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
30d20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30d30 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
30d40 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
30d50 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
30d60 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
30d70 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
30d80 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
30d90 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
30da0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
30db0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
30dc0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
30dd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
30de0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
30df0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
30e00 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
30e10 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
30e20 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
30e30 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
30e40 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
30e50 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
30e60 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
30e70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
30e80 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
30e90 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
30ea0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
30eb0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
30ec0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
30ed0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
30ee0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
30ef0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
30f00 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
30f10 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
30f20 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
30f30 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
30f40 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
30f50 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
30f60 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
30f70 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
30f80 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
30f90 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
30fa0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
30fb0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
30fc0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
30fd0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
30fe0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
30ff0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
31000 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
31010 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
31020 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
31030 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
31040 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
31050 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
31060 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
31070 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
31080 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
31090 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
310a0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
310b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
310c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
310d0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
310e0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
310f0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
31100 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
31110 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
31120 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
31130 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
31140 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
31150 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
31160 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
31170 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
31180 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
31190 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
311a0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
311b0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
311c0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
311d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
311e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
311f0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
31200 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
31210 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
31220 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
31230 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
31240 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
31250 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
31260 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
31270 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
31280 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
31290 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
312a0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
312b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
312c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
312d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
312e0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
312f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
31300 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
31310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
31320 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
31330 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
31340 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31350 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31360 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31370 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
31380 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
31390 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
313a0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
313b0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
313c0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
313d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
313e0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
313f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
31400 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
31410 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
31420 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
31430 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
31440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
31450 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
31460 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
31470 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
31480 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31490 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
314a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
314b0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
314c0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
314d0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
314e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
314f0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
31500 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
31510 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
31520 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
31530 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31540 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
31550 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
31560 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31570 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
31580 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
31590 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
315a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
315b0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
315c0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
315d0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
315e0 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
315f0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
31600 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
31610 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
31620 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
31630 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
31640 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
31650 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
31660 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
31670 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31680 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
31690 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
316a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
316b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
316c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
316d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
316e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
316f0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
31700 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
31710 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
31720 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
31730 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
31740 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
31750 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
31760 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
31770 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
31780 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31790 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
317a0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
317b0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
317c0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
317d0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
317e0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
317f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
31800 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
31810 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
31820 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
31830 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
31840 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
31850 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
31860 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
31870 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
31880 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
31890 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
318a0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
318b0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
318c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
318d0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
318e0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
318f0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
31900 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
31910 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
31920 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
31930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31940 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
31950 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
31960 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
31970 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
31980 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
31990 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
319a0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
319b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
319c0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
319d0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
319e0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
319f0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
31a00 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
31a10 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
31a20 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
31a30 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
31a40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31a50 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
31a60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31a70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
31a80 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
31a90 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
31aa0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
31ab0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
31ac0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
31ad0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
31ae0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
31af0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
31b00 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31b10 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
31b20 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
31b30 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
31b40 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
31b50 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
31b60 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
31b70 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
31b80 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
31b90 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
31ba0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
31bb0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
31bc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
31bd0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
31be0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
31bf0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
31c00 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
31c10 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
31c20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
31c30 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
31c40 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
31c50 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
31c60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31c70 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
31c80 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
31c90 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
31ca0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
31cb0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
31cc0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
31cd0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
31ce0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
31cf0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
31d00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31d10 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
31d20 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
31d30 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31d40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31d50 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
31d60 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
31d70 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
31d80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31d90 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
31da0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
31db0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
31dc0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
31dd0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
31de0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
31df0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
31e00 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
31e10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31e20 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
31e30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
31e40 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
31e50 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
31e60 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
31e70 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
31e80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
31e90 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31ea0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
31eb0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
31ec0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
31ed0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
31ee0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
31ef0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
31f00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31f10 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
31f20 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
31f30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
31f40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
31f60 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
31f70 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
31f80 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
31f90 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
31fa0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
31fb0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
31fc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
31fd0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
31fe0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
31ff0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
32000 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
32010 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
32020 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
32030 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
32040 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
32050 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
32070 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
32080 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
32090 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
320a0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
320b0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
320c0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
320d0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
320e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
320f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32100 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
32110 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
32120 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
32130 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
32140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32160 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
32170 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
32180 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
32190 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
321a0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
321b0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
321c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
321d0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
321e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
321f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
32200 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
32210 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
32220 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
32230 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
32240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32250 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
32260 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
32270 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
32280 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32290 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
322a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
322b0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
322c0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
322d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
322e0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
322f0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
32300 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
32310 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
32320 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
32330 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32340 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
32350 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
32360 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
32370 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32380 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
32390 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
323a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
323b0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
323c0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
323d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
323e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
323f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32400 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32410 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
32420 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
32430 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32440 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
32450 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32460 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
32470 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
32480 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
32490 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
324a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
324b0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
324c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
324d0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
324e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
324f0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
32500 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
32510 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
32520 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
32530 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
32540 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32550 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32560 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32570 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32580 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
32590 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
325a0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
325b0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
325c0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
325d0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
325e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
325f0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
32600 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32610 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
32620 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
32630 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
32640 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
32650 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
32660 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
32670 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
32680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32690 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
326a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
326b0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
326c0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
326d0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
326e0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
326f0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
32700 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
32710 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32720 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
32730 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32740 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
32750 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
32760 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
32770 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
32780 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
32790 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
327a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
327b0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
327c0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
327d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
327e0 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
327f0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
32800 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32810 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
32820 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
32830 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32840 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
32850 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
32860 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
32870 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
32880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
32890 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
328a0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
328b0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
328c0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
328d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
328e0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
328f0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
32900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32910 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
32920 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
32930 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
32940 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
32950 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
32960 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
32970 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
32980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
32990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
329a0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
329b0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
329c0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
329d0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
329e0 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
329f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32a00 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
32a10 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
32a20 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
32a30 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
32a40 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
32a50 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
32a60 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
32a70 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
32a80 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
32a90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
32aa0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
32ab0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
32ac0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
32ad0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
32ae0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
32af0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
32b00 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
32b10 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
32b20 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
32b30 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
32b40 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
32b50 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
32b60 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
32b70 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
32b80 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
32b90 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
32ba0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
32bb0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
32bc0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
32bd0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32be0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32bf0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
32c00 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
32c10 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
32c20 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
32c30 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
32c40 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
32c50 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
32c60 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
32c70 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
32c80 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
32c90 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
32ca0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
32cb0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
32cc0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
32cd0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
32ce0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32cf0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
32d00 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
32d10 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
32d20 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
32d30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
32d40 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
32d50 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
32d60 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
32d70 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
32d80 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
32d90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
32da0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
32db0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
32dc0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
32dd0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
32de0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
32df0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
32e00 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
32e10 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32e20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
32e30 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32e40 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
32e50 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32e60 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
32e70 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
32e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
32e90 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
32ea0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
32eb0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
32ec0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
32ed0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
32ee0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
32ef0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
32f00 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
32f10 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32f20 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
32f30 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
32f40 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
32f50 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
32f60 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
32f70 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
32f80 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
32f90 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
32fa0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
32fb0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
32fc0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
32fd0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
32fe0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
32ff0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
33000 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
33010 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
33020 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33030 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
33040 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
33050 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
33060 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
33070 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
33080 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
33090 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
330a0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
330b0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
330c0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
330d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
330e0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
330f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33100 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
33110 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
33120 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
33130 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
33140 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
33150 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
33160 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
33170 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
33180 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
33190 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
331a0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
331b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
331c0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
331d0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
331e0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
331f0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
33200 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
33210 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
33220 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
33230 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
33240 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
33250 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
33260 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
33270 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
33280 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
33290 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
332a0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
332b0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
332c0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
332d0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
332e0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
332f0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
33300 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
33310 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
33320 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
33330 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
33340 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
33350 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
33360 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
33370 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
33380 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
33390 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
333a0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
333b0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
333c0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
333d0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
333e0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
333f0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
33400 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
33410 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
33420 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
33430 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
33440 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
33450 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
33460 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
33470 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
33480 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
33490 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
334a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
334b0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
334c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
334d0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
334e0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
334f0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
33500 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33510 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
33520 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
33530 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
33540 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33560 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
33570 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
33580 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
33590 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
335a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
335b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
335c0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
335d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
335e0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
335f0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
33600 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
33610 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
33620 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
33630 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
33640 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33650 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
33660 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
33670 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
33680 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
33690 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
336a0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
336b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
336c0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
336d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
336e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
336f0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
33700 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
33710 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
33720 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
33730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33740 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
33750 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
33760 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
33770 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
33780 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
33790 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
337a0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
337b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
337c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
337d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
337e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
337f0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
33800 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
33810 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
33820 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
33830 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
33840 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
33850 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
33860 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33870 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
33880 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33890 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
338a0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
338b0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
338c0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
338d0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
338e0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
338f0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
33900 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
33910 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
33920 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
33930 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
33940 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
33950 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
33960 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
33970 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
33980 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
33990 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
339a0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
339b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
339c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
339d0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
339e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
339f0 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
33a00 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
33a10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33a30 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
33a40 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
33a50 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
33a60 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33a70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
33a80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33a90 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33aa0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
33ab0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33ac0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
33ad0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33ae0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33af0 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45  PI double SQLITE
33b00 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33b10 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
33b20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33b30 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33b40 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
33b50 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33b60 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
33b70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33b80 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
33b90 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
33ba0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
33bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33bd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33be0 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
33bf0 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54  gned char *SQLIT
33c00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33c10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
33c20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33c30 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33c40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
33c50 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33c70 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
33c80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33c90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
33ca0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
33cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33cd0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33ce0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
33cf0 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ue *SQLITE_STDCA
33d00 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33d10 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
33d20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33d30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d40 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
33d50 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
33d60 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
33d70 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
33d80 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
33d90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33da0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
33db0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
33dc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33dd0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
33de0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
33df0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
33e00 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
33e10 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
33e20 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
33e30 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
33e40 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
33e50 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
33e60 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
33e70 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
33e80 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33e90 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
33ea0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
33eb0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
33ec0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
33ed0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
33ee0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
33ef0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
33f00 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
33f10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33f20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33f30 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
33f40 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
33f50 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
33f60 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
33f70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33f80 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
33f90 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
33fa0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
33fb0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
33fc0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
33fd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33fe0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
33ff0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
34000 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
34010 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
34020 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
34030 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
34040 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
34050 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
34060 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
34070 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
34080 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
34090 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
340a0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
340b0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
340c0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
340d0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
340e0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
340f0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
34100 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
34110 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
34120 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
34130 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
34140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34150 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
34160 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
34170 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
34180 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
34190 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
341a0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
341b0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
341c0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
341d0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
341e0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
341f0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
34200 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
34210 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
34220 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34230 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
34240 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
34250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34260 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
34270 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
34280 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
34290 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
342a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
342b0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
342c0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
342d0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
342e0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
342f0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
34300 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
34310 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
34320 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
34330 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
34340 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
34350 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
34360 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
34370 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
34380 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
34390 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
343a0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
343b0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
343c0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
343d0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
343e0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
343f0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
34400 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
34410 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
34420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34430 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
34440 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
34450 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
34460 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
34470 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
34480 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
34490 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
344a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
344b0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
344c0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
344d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
344e0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
344f0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
34500 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
34510 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
34520 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
34530 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
34540 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
34550 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34560 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
34570 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
34580 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
34590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
345a0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
345b0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
345c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
345d0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
345e0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
345f0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
34600 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34610 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
34620 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
34630 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
34640 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
34650 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
34660 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
34670 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
34680 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34690 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
346a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
346b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
346c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
346d0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
346e0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
346f0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
34700 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
34710 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
34720 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34730 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
34750 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34760 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34770 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
34780 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34790 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
347a0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
347b0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
347c0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
347d0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
347e0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
347f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
34800 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
34810 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
34820 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
34830 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
34840 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
34850 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
34860 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
34870 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
34880 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
34890 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
348a0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
348b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
348c0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
348d0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
348e0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
348f0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
34900 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
34910 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
34920 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
34930 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34940 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
34950 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34960 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
34970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
34980 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
34990 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
349a0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
349b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
349c0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
349d0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
349e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
349f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34a00 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
34a10 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
34a20 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
34a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
34a40 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34a50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
34a60 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
34a70 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
34a80 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
34a90 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
34aa0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
34ab0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
34ac0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
34ad0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
34ae0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
34af0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
34b00 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
34b10 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
34b20 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
34b30 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
34b40 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
34b50 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
34b60 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
34b70 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
34b80 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
34b90 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
34ba0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
34bb0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
34bc0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
34bd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
34be0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
34bf0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
34c00 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
34c10 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
34c20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34c30 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
34c40 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
34c50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
34c60 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
34c70 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
34c80 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
34c90 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
34ca0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
34cb0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
34cc0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
34cd0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
34ce0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
34cf0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
34d00 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
34d10 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
34d20 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
34d30 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
34d40 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
34d50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34d60 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
34d70 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
34d80 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
34d90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
34da0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
34db0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
34dc0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
34dd0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
34de0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
34df0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
34e00 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
34e10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
34e20 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
34e30 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34e40 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
34e50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34e60 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
34e70 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
34e80 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
34e90 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
34ea0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
34eb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34ec0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
34ed0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
34ee0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
34ef0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34f00 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
34f10 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
34f20 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
34f30 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
34f40 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
34f50 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
34f60 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
34f70 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
34f80 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
34f90 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
34fa0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
34fb0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
34fc0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
34fd0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
34fe0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
34ff0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
35000 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
35010 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
35020 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
35030 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
35040 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
35050 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
35060 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
35070 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
35080 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
35090 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
350a0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
350b0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
350c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
350d0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
350e0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
350f0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
35100 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
35110 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
35120 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
35130 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
35140 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
35150 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
35160 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
35170 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
35180 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
35190 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
351a0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
351b0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
351c0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
351d0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
351e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
351f0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
35200 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
35210 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
35220 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
35230 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
35240 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
35250 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
35260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
35270 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
35280 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
35290 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
352a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
352b0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
352c0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
352d0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
352e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
352f0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
35300 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
35310 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
35320 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
35330 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
35340 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
35350 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
35360 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
35370 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
35380 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
35390 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
353a0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
353b0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
353c0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
353d0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
353e0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
353f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
35400 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
35410 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
35420 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
35430 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
35440 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
35450 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
35460 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
35470 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
35480 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
35490 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
354a0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
354b0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
354c0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
354d0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
354e0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
354f0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
35500 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
35510 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
35520 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
35530 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35540 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35550 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
35560 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
35570 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
35580 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
35590 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
355a0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
355b0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
355c0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
355d0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
355e0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
355f0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
35600 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
35610 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
35620 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
35630 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
35640 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
35650 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
35660 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35670 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
35680 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
35690 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
356a0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
356b0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
356c0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
356d0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
356e0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
356f0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
35700 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
35710 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
35720 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
35730 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35740 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35750 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
35760 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
35770 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
35780 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35790 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
357a0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
357b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
357c0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
357d0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
357e0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
357f0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
35800 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35810 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
35820 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
35830 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35840 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
35850 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
35860 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
35870 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
35880 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
35890 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
358a0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
358b0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
358c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
358d0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
358e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
358f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
35900 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
35910 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
35920 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
35930 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35940 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
35950 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
35960 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
35970 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
35980 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35990 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
359a0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
359b0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
359c0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
359d0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
359e0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
359f0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
35a00 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
35a10 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
35a20 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35a30 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
35a40 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
35a50 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
35a60 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
35a70 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
35a80 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
35a90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35aa0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
35ab0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
35ac0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35ad0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
35ae0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
35af0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
35b00 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
35b10 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
35b20 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
35b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35b40 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
35b50 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
35b60 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
35b70 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
35b80 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35b90 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
35ba0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
35bb0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65  CALL sqlite3_cre
35bc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
35bd0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
35be0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
35bf0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
35c00 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
35c10 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
35c20 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
35c30 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35c40 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35c50 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35c60 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35c70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35c90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
35ca0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
35cb0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
35cc0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
35cd0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
35ce0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35cf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
35d00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
35d10 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
35d20 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
35d30 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
35d40 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
35d50 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
35d60 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35d70 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35d80 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
35d90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35da0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35db0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
35dc0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
35dd0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
35de0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
35df0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35e00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35e10 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
35e20 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
35e30 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
35e40 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
35e50 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
35e60 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
35e70 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
35e80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35ea0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
35eb0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35ec0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35ed0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35ee0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
35ef0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
35f00 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
35f10 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
35f20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
35f30 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
35f40 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
35f50 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
35f60 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
35f70 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
35f80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
35f90 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
35fa0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
35fb0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
35fc0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
35fd0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
35fe0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35ff0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
36000 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
36010 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
36020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
36030 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
36040 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
36050 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
36060 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
36070 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
36080 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
36090 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
360a0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
360b0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
360c0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
360d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
360e0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
360f0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
36100 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
36110 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
36120 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
36130 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
36140 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
36150 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
36160 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
36170 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
36180 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
36190 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
361a0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
361b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
361c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
361d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
361e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
361f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
36200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
36210 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
36220 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
36230 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
36240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
36250 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
36260 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
36270 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
36280 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
36290 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
362a0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
362b0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
362c0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
362d0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
362e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
362f0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
36300 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
36310 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
36320 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
36330 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
36340 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
36350 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
36360 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
36370 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
36380 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
36390 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
363a0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
363b0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
363c0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
363d0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
363e0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
363f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36400 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36410 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
36420 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
36430 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36440 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
36450 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
36460 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
36470 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
36480 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36490 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
364a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
364b0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
364c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
364d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
364e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
364f0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36500 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36510 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
36520 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
36530 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36540 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
36550 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36560 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
36570 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
36580 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
36590 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
365a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
365b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
365c0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
365d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
365e0 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
365f0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
36600 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
36610 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
36620 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
36630 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
36640 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36650 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
36660 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
36670 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
36680 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
36690 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
366a0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
366b0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
366c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
366d0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
366e0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
366f0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
36700 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
36710 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
36720 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
36730 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
36740 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
36750 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36760 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36770 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
36780 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36790 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
367a0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
367b0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
367c0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
367d0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
367e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
367f0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
36800 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
36810 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
36820 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36830 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36840 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
36850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36860 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
36870 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36880 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
36890 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
368a0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
368b0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
368c0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
368d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
368e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
368f0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
36900 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
36910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36920 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
36930 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
36940 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
36950 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
36960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
36970 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
36980 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
36990 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
369a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
369b0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
369c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
369d0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
369e0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
369f0 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
36a00 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
36a10 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
36a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36a30 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
36a40 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
36a50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
36a60 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
36a70 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
36a80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
36a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36aa0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
36ab0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
36ac0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
36ad0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
36ae0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
36af0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
36b00 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
36b10 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
36b20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36b30 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
36b40 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
36b50 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
36b60 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
36b70 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
36b80 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
36b90 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
36ba0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
36bb0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
36bc0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
36bd0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
36be0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
36bf0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
36c00 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
36c10 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
36c20 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
36c30 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
36c40 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
36c50 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
36c60 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
36c70 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
36c80 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
36c90 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
36ca0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
36cb0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
36cc0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
36cd0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
36ce0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
36cf0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
36d00 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
36d10 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
36d20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
36d30 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
36d40 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
36d50 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
36d60 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
36d70 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
36d80 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
36d90 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
36da0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
36db0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
36dc0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
36dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36de0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
36df0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36e00 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
36e10 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
36e20 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
36e30 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36e40 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
36e50 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
36e60 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
36e70 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
36e80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
36e90 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
36ea0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36eb0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
36ec0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
36ed0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
36ee0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
36ef0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
36f00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
36f10 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
36f20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
36f30 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
36f40 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36f50 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
36f60 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36f70 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
36f80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36f90 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
36fa0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
36fb0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
36fc0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36fd0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
36fe0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36ff0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
37000 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
37010 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
37020 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
37030 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37040 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
37050 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
37060 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
37070 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
37080 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
37090 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
370a0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
370b0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
370c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
370d0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
370e0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
370f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
37100 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
37110 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
37120 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
37130 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
37140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37150 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
37160 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
37170 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
37180 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37190 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
371a0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
371b0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
371c0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
371d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
371e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
371f0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
37200 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37210 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
37220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
37230 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37240 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
37250 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
37260 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
37270 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
37280 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
372a0 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
372b0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
372c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
372d0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
372e0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
372f0 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
37300 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
37310 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
37320 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
37330 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37340 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
37350 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
37360 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
37370 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
37380 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
37390 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
373a0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
373b0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
373c0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
373d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
373e0 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
373f0 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
37400 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
37410 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
37420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
37430 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
37440 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
37450 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
37460 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
37470 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
37480 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
37490 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
374a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
374b0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
374c0 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
374d0 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  her..*/.SQLITE_A
374e0 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  PI unsigned int 
374f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
37500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
37510 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37520 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37530 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
37540 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
37550 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37560 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
37570 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37580 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
37590 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
375a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
375b0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
375c0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
375d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
375e0 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
375f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
37600 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
37610 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37620 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
37630 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
37640 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
37650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
37660 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
37670 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
37680 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
37690 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
376a0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
376b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
376c0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
376d0 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
376e0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
376f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
37700 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
37710 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
37720 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
37730 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
37740 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
37750 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37760 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
37770 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
37780 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
37790 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  lue *SQLITE_STDC
377a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
377b0 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
377c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
377d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
377e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
377f0 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
37800 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37820 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
37830 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
37840 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
37850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37860 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
37870 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
37880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
37890 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
378a0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
378b0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
378c0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
378d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
378e0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
378f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37900 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
37910 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
37920 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
37930 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37940 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
37950 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
37960 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
37970 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
37980 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37990 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
379a0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
379b0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
379c0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
379d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
379e0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
379f0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
37a00 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
37a10 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
37a20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
37a30 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
37a40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37a50 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
37a60 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
37a70 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
37a80 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
37a90 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
37aa0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
37ab0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
37ac0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37ad0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
37ae0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
37af0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
37b00 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
37b10 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
37b20 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
37b30 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37b40 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
37b50 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
37b60 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
37b70 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
37b80 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
37b90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37ba0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
37bb0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
37bc0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
37bd0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
37be0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
37bf0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37c00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
37c10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
37c20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
37c30 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
37c40 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
37c50 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
37c60 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
37c70 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37c80 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
37c90 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
37ca0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
37cb0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
37cc0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37cd0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
37ce0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
37cf0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
37d00 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
37d10 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
37d20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
37d30 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
37d40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
37d50 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37d60 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
37d70 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
37d80 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
37d90 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
37da0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
37db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
37dc0 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
37dd0 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
37de0 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
37df0 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
37e00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
37e10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37e20 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
37e30 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
37e40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
37e50 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
37e60 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
37e70 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
37e80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
37e90 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
37ea0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37eb0 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
37ec0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
37ed0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
37ee0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
37ef0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
37f00 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
37f10 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
37f20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
37f30 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
37f40 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
37f50 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
37f60 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37f70 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
37f80 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
37f90 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
37fa0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
37fb0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
37fc0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
37fd0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
37fe0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
37ff0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
38000 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
38010 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38020 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
38030 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
38040 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
38050 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
38060 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
38070 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
38080 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
38090 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
380a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
380b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
380c0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
380d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
380e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
380f0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
38100 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
38110 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
38120 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
38130 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
38140 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
38150 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
38160 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38170 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
38180 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
38190 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
381a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
381b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
381c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
381d0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
381e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
381f0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
38200 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
38210 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
38220 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
38230 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
38240 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
38250 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72  ALL sqlite3_user
38260 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
38270 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
38280 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
38290 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
382a0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
382b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
382c0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
382d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
382e0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
382f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38300 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
38310 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
38320 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38330 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
38340 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
38350 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
38360 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
38370 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
38380 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
38390 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
383a0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
383b0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
383c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
383d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
383e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
383f0 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  te3 *SQLITE_STDC
38400 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ALL sqlite3_cont
38410 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
38420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
38430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38440 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
38450 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
38460 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
38470 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
38480 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
38490 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
384a0 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
384b0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
384c0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
384d0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
384e0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
384f0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
38500 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
38510 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
38520 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
38530 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
38540 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
38550 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
38560 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
38570 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
38580 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
38590 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
385a0 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
385b0 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
385c0 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
385d0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
385e0 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
385f0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
38600 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
38610 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
38620 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
38630 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
38640 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38650 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
38660 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
38670 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
38680 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
38690 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
386a0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
386b0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
386c0 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
386d0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
386e0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
386f0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
38700 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38710 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
38720 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38730 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
38740 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
38750 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
38760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38770 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() func