System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ec02bcee6fd6da0268b51b3d784e2b274f54e2e5:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 38 2e 31 31 2e 20 20  ersion 3.8.11.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d  e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72  ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56   options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c  C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20  d be done first 
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76  uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20  ent spurious.** 
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75  s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74  ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68  his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74  er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79   are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f   this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e  nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68  egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72  *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73  s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e  pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56  .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53  C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e  VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72  ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72  able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72  able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72  able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72  able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72  able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72  able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72  able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72  able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72  able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72  able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72  able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72  able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72  able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72  able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e  able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f  dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e  MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20  dif /* _MSVC_H_ 
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e  *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77  *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66  here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   in sqliteInt.h 
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57  al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65  vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a  le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54  15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57  is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f  ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64  ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e  efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56  EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20  xWorks.  Set up 
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79  things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a   for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b  #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70  s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d  thread.h>  /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63  algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ache */.#define 
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65  OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f  fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53  THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f  QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20  RECURSIVE_MUTEX 
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e  _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53  SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43  QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65  KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20  fine HAVE_UTIME 
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20  1.#else./* This 
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20  is not VxWorks. 
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f  WORKS 0.#endif /
11f0: 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b  * defined(_WRS_K
1200: 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a  ERNEL) */../****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f  ********** End o
1220: 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  f vxworks.h ****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69  ********** Conti
1270: 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c  nuing where we l
1280: 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74  eft off in sqlit
1290: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a  *********/../*.*
12b0: 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73  * These #defines
12c0: 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e   should enable >
12d0: 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74  2GB file support
12e0: 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65   on POSIX if the
12f0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  .** underlying o
1300: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1310: 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66  supports it.  If
1320: 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a   the OS lacks.**
1330: 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70   large file supp
1340: 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f  ort, or if the O
1350: 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68  S is windows, th
1360: 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f  ese should be no
1370: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b  -ops..**.** Tick
1380: 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f  et #2739:  The _
1390: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
13a0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65   macro must appe
13b0: 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a  ar before any.**
13c0: 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65   system #include
13d0: 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20  s.  Hence, this 
13e0: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75  block of code mu
13f0: 73 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66  st be the very f
1400: 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20  irst.** code in 
1410: 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73  all source files
1420: 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69  ..**.** Large fi
1430: 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62  le support can b
1440: 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  e disabled using
1450: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49   the -DSQLITE_DI
1460: 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68  SABLE_LFS switch
1470: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  .** on the compi
1480: 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65  ler command line
1490: 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73  .  This is neces
14a0: 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20  sary if you are 
14b0: 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20  compiling.** on 
14c0: 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65  a recent machine
14d0: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e   (ex: Red Hat 7.
14e0: 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20  2) but you want 
14f0: 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72  your code to wor
1500: 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72  k.** on an older
1510: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
1520: 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20  d Hat 6.0).  If 
1530: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52  you compile on R
1540: 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69  ed Hat 7.2.** wi
1550: 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f  thout this optio
1560: 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65  n, LFS is enable
1570: 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20  .  But LFS does 
1580: 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65  not exist in the
1590: 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65   kernel.** in Re
15a0: 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68  d Hat 6.0, so th
15b0: 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72  e code won't wor
15c0: 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d  k.  Hence, for m
15d0: 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a  aximum binary.**
15e0: 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75   portability you
15f0: 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53   should omit LFS
1600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76  ..**.** The prev
1610: 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77  ious paragraph w
1620: 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30  as written in 20
1630: 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67  05.  (This parag
1640: 72 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a  raph is written.
1650: 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38  ** on 2008-11-28
1660: 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61  .) These days, a
1670: 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73  ll Linux kernels
1680: 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66   support large f
1690: 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20  iles, so.** you 
16a0: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20  should probably 
16b0: 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65  leave LFS enable
16c0: 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62  d.  But some emb
16d0: 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20  edded platforms 
16e0: 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46  might.** lack LF
16f0: 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  S in which case 
1700: 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42  the SQLITE_DISAB
1710: 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67  LE_LFS macro mig
1720: 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66  ht still be usef
1730: 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61  ul..**.** Simila
1740: 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61  r is true for Ma
1750: 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20  c OS X.  LFS is 
1760: 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f  only supported o
1770: 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64  n Mac OS X 9 and
1780: 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64   later..*/.#ifnd
1790: 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  ef SQLITE_DISABL
17a0: 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f  E_LFS.# define _
17b0: 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20  LARGE_FILE      
17c0: 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c   1.# ifndef _FIL
17d0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20  E_OFFSET_BITS.# 
17e0: 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f    define _FILE_O
17f0: 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20  FFSET_BITS 64.# 
1800: 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f  endif.# define _
1810: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
1820: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65   1.#endif../* Ne
1830: 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 73  eded for various
1840: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20   definitions... 
1850: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
1860: 5f 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65 66  _GNUC__) && !def
1870: 69 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45  ined(_GNU_SOURCE
1880: 29 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f  ).# define _GNU_
1890: 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23  SOURCE.#endif..#
18a0: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65  if defined(__Ope
18b0: 6e 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66 69  nBSD__) && !defi
18c0: 6e 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45 29  ned(_BSD_SOURCE)
18d0: 0a 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f 53  .# define _BSD_S
18e0: 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a  OURCE.#endif../*
18f0: 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63  .** For MinGW, c
1900: 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 77  heck to see if w
1910: 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74 68  e can include th
1920: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 63 6f  e header file co
1930: 6e 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20  ntaining its.** 
1940: 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74  version informat
1950: 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72  ion, among other
1960: 20 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c   things.  Normal
1970: 6c 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e 61  ly, this interna
1980: 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65  l MinGW.** heade
1990: 72 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e  r file would [on
19a0: 6c 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64 20  ly] be included 
19b0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
19c0: 20 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65 61   other MinGW hea
19d0: 64 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f  der.** files; ho
19e0: 77 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74 61  wever, the conta
19f0: 69 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e 66  ined version inf
1a00: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20  ormation is now 
1a10: 72 65 71 75 69 72 65 64 20 62 79 20 74 68 69 73  required by this
1a20: 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20  .** header file 
1a30: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62  to work around b
1a40: 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c  inary compatibil
1a50: 69 74 79 20 69 73 73 75 65 73 20 28 73 65 65 20  ity issues (see 
1a60: 62 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68  below) and.** th
1a70: 69 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b  is is the only k
1a80: 6e 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c 69  nown way to reli
1a90: 61 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e 20  ably obtain it. 
1aa0: 20 54 68 69 73 20 65 6e 74 69 72 65 20 23 69 66   This entire #if
1ab0: 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20   block.** would 
1ac0: 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e  be completely un
1ad0: 6e 65 63 65 73 73 61 72 79 20 69 66 20 74 68 65  necessary if the
1ae0: 72 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65 72  re was any other
1af0: 20 77 61 79 20 6f 66 20 64 65 74 65 63 74 69 6e   way of detectin
1b00: 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20 74  g.** MinGW via t
1b10: 68 65 69 72 20 70 72 65 70 72 6f 63 65 73 73 6f  heir preprocesso
1b20: 72 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79 20  r (e.g. if they 
1b30: 63 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69 72  customized their
1b40: 20 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a   GCC to define.*
1b50: 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65  * some MinGW-spe
1b60: 63 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20 20  cific macros).  
1b70: 57 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66  When compiling f
1b80: 6f 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65 72  or MinGW, either
1b90: 20 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49   the.** _HAVE_MI
1ba0: 4e 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f  NGW_H or _HAVE__
1bb0: 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74 68  MINGW_H (note th
1bc0: 65 20 65 78 74 72 61 20 75 6e 64 65 72 73 63 6f  e extra undersco
1bd0: 72 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20 62  re) macro must b
1be0: 65 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74  e.** defined; ot
1bf0: 68 65 72 77 69 73 65 2c 20 64 65 74 65 63 74 69  herwise, detecti
1c00: 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73  on of conditions
1c10: 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69 6e   specific to Min
1c20: 47 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69  GW will be.** di
1c30: 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64  sabled..*/.#if d
1c40: 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e  efined(_HAVE_MIN
1c50: 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20  GW_H).# include 
1c60: 22 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20  "mingw.h".#elif 
1c70: 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d  defined(_HAVE__M
1c80: 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64  INGW_H).# includ
1c90: 65 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e  e "_mingw.h".#en
1ca0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d  dif../*.** For M
1cb0: 69 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e 78  inGW version 4.x
1cc0: 20 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20 63   (and higher), c
1cd0: 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 74  heck to see if t
1ce0: 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49  he _USE_32BIT_TI
1cf0: 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69  ME_T.** define i
1d00: 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d 61  s required to ma
1d10: 69 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63 6f  intain binary co
1d20: 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
1d30: 20 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69 6d   the MSVC runtim
1d40: 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e 20  e.** library in 
1d50: 75 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57 69  use (e.g. for Wi
1d60: 6e 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69  ndows XP)..*/.#i
1d70: 66 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f  f !defined(_USE_
1d80: 33 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26  32BIT_TIME_T) &&
1d90: 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 36   !defined(_USE_6
1da0: 34 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20  4BIT_TIME_T) && 
1db0: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 57  \.    defined(_W
1dc0: 49 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e 65  IN32) && !define
1dd0: 64 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a 20  d(_WIN64) && \. 
1de0: 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e     defined(__MIN
1df0: 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e  GW_MAJOR_VERSION
1e00: 29 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a  ) && __MINGW_MAJ
1e10: 4f 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20  OR_VERSION >= 4 
1e20: 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64  && \.    defined
1e30: 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64  (__MSVCRT__).# d
1e40: 65 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49 54  efine _USE_32BIT
1e50: 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a  _TIME_T.#endif..
1e60: 2f 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53 51  /* The public SQ
1e70: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
1e80: 20 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45   The _FILE_OFFSE
1e90: 54 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75 73  T_BITS macro mus
1ea0: 74 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72 73  t appear.** firs
1eb0: 74 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c  t in QNX.  Also,
1ec0: 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f   the _USE_32BIT_
1ed0: 54 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73  TIME_T macro mus
1ee0: 74 20 61 70 70 65 61 72 20 66 69 72 73 74 20 66  t appear first f
1ef0: 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a  or.** MinGW..*/.
1f00: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
1f10: 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e  Include sqlite3.
1f20: 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  h in the middle 
1f30: 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a  of sqliteInt.h *
1f40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
1f50: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
1f60: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
1f70: 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e3.h ***********
1f80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
1fa0: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
1fb0: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
1fc0: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
1fd0: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
1fe0: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
1ff0: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
2000: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
2010: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
2020: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
2030: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
2040: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
2050: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
2060: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
2070: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
2080: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
2090: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
20a0: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
20b0: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
20c0: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
20d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2100: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2110: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
2120: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
2130: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
2140: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
2150: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
2160: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
2170: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
2180: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
2190: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
21a0: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
21b0: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
21c0: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
21d0: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
21e0: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
21f0: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
2200: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
2210: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
2220: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
2230: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
2240: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
2250: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
2260: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
2270: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
2280: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
2290: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
22a0: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
22b0: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
22c0: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
22d0: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
22e0: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
22f0: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
2300: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
2310: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
2320: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
2330: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
2340: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
2350: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
2360: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
2370: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
2380: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
2390: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
23a0: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
23b0: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
23c0: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
23d0: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
23e0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
23f0: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
2400: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
2410: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
2420: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
2430: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
2440: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
2450: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
2460: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
2470: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
2480: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
2490: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
24a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
24b0: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
24c0: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
24d0: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
24e0: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
24f0: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
2500: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
2510: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
2520: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
2530: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
2540: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
2550: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
2560: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
2570: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
2580: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
2590: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
25a0: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
25b0: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
25c0: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
25d0: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
25e0: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
25f0: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
2600: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
2610: 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20  */.#if 0.extern 
2620: 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f  "C" {.#endif.../
2630: 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65  *.** Provide the
2640: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72   ability to over
2650: 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61  ride linkage fea
2660: 74 75 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74  tures of the int
2670: 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64  erface..*/.#ifnd
2680: 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ef SQLITE_EXTERN
2690: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
26a0: 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23  _EXTERN extern.#
26b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
26c0: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
26d0: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
26e0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
26f0: 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e  TE_CDECL.# defin
2700: 65 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23  e SQLITE_CDECL.#
2710: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
2720: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
2730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
2740: 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  CALL.#endif../*.
2750: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d  ** These no-op m
2760: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69  acros are used i
2770: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72  n front of inter
2780: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68  faces to mark th
2790: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ose.** interface
27a0: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72  s as either depr
27b0: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69  ecated or experi
27c0: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70  mental.  New app
27d0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
27e0: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72  uld not use depr
27f0: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65  ecated interface
2800: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
2810: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2820: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2830: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
2840: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
2850: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
2860: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
2870: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
2880: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
2890: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
28a0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
28b0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
28c0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
28d0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
28e0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
28f0: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
2900: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
2910: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
2920: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
2930: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
2940: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
2950: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
2960: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
2970: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
2980: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
2990: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
29a0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
29b0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
29c0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
29d0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
29e0: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
29f0: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
2a00: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
2a10: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
2a20: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
2a30: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
2a40: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
2a50: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
2a60: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
2a70: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
2a80: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
2a90: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
2aa0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2ab0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
2ac0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2ad0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
2ae0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
2af0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
2b00: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
2b10: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
2b20: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
2b30: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
2b40: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
2b50: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
2b60: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
2b70: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
2b80: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
2b90: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
2ba0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
2bb0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
2bc0: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
2bd0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
2be0: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
2bf0: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
2c00: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
2c10: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
2c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
2c30: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
2c40: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
2c50: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
2c60: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
2c70: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
2c80: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
2c90: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
2ca0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
2cb0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
2cc0: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
2cd0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
2ce0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
2cf0: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
2d00: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
2d10: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
2d20: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
2d30: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
2d40: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
2d50: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
2d60: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
2d70: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
2d80: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
2d90: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
2da0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
2db0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
2dc0: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
2dd0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
2de0: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
2df0: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
2e00: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
2e10: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
2e20: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
2e30: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
2e40: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
2e50: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
2e60: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
2e70: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
2e80: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
2e90: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
2ea0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
2eb0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
2ec0: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
2ed0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
2ee0: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
2ef0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
2f00: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
2f10: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
2f20: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
2f30: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
2f40: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
2f50: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
2f60: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
2f70: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
2f80: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
2f90: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
2fa0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
2fb0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
2fc0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
2fd0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
2fe0: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ff0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
3000: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
3010: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
3020: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
3030: 20 20 20 20 20 20 20 22 33 2e 38 2e 31 31 22 0a         "3.8.11".
3040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
3050: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30  ERSION_NUMBER 30
3060: 30 38 30 31 31 0a 23 64 65 66 69 6e 65 20 53 51  08011.#define SQ
3070: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
3080: 20 20 20 20 22 32 30 31 35 2d 30 35 2d 33 30 20      "2015-05-30 
3090: 32 32 3a 30 35 3a 31 37 20 37 33 66 63 30 35 38  22:05:17 73fc058
30a0: 62 33 61 37 34 63 31 62 30 31 38 63 66 66 39 39  b3a74c1b018cff99
30b0: 30 64 65 37 39 33 66 31 39 61 36 30 32 63 31 32  0de793f19a602c12
30c0: 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  f"../*.** CAPI3R
30d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
30e0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
30f0: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
3100: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
3110: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
3120: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
3130: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
3140: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
3150: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
3160: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
3170: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
3180: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
3190: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
31a0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
31b0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
31c0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
31d0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
31e0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
31f0: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
3200: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
3210: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
3220: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
3230: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
3240: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
3250: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
3260: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
3270: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
3280: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
3290: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
32a0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
32b0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
32c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
32d0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
32e0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
32f0: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
3300: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
3310: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
3320: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
3330: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
3340: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
3350: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
3360: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
3370: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3380: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
3390: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
33a0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
33b0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
33c0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
33d0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
33e0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
33f0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3400: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
3410: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
3420: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
3430: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
3440: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
3450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
3460: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
3470: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
3480: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
3490: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
34a0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
34b0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
34c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
34d0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
34e0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
34f0: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
3500: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
3510: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
3520: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
3530: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
3540: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
3550: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
3560: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
3570: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
3580: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
3590: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
35a0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
35b0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
35c0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
35d0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
35e0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
35f0: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
3600: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
3610: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
3620: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
3630: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
3640: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
3650: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
3660: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
3670: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
3680: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
3690: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
36a0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
36b0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
36c0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
36d0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
36e0: 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
36f0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
3700: 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ion(void);.SQLIT
3710: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
3720: 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
3730: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
3740: 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
3750: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
3760: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c  TDCALL sqlite3_l
3770: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
3780: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
3790: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
37a0: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
37b0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
37c0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
37d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
37e0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
37f0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3800: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
3810: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
3820: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
3830: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
3840: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
3850: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
3860: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
3870: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
3880: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
3890: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
38a0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
38b0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
38c0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38d0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
38e0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
38f0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
3900: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
3910: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
3920: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
3930: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
3940: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
3950: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
3960: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
3970: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
3980: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
3990: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
39a0: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
39b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
39c0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
39d0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
39e0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
39f0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
3a00: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
3a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
3a20: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
3a30: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
3a40: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
3a50: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
3a60: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
3a70: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
3a80: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
3a90: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
3aa0: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
3ab0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
3ac0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
3ad0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
3ae0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
3af0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
3b00: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
3b10: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
3b20: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
3b30: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
3b40: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
3b50: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
3b60: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
3b70: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
3b80: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
3b90: 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54  TION_DIAGS.SQLIT
3ba0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
3bb0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3bc0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
3bd0: 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  sed(const char *
3be0: 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54  zOptName);.SQLIT
3bf0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
3c00: 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
3c10: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3c20: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
3c30: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
3c40: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
3c50: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
3c60: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
3c70: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
3c80: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
3c90: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
3ca0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
3cb0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
3cc0: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
3cd0: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
3ce0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
3cf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
3d00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
3d10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
3d20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
3d30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
3d40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
3d50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
3d60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
3d70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
3d80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
3d90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
3da0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
3db0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
3dc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
3dd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
3de0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
3df0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
3e00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
3e10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
3e20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
3e30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
3e40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
3e50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
3e60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
3e70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
3e80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
3e90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
3ea0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
3eb0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
3ec0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
3ed0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
3ee0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
3ef0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
3f00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
3f10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
3f20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
3f30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
3f40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
3f50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
3f60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
3f70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
3f80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
3f90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
3fa0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
3fb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
3fc0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
3fd0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
3fe0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
3ff0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
4000: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
4010: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
4020: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
4030: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
4040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
4050: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
4060: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
4070: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
4080: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
4090: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
40a0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
40b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
40c0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
40d0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
40e0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
40f0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
4100: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
4110: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
4120: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
4130: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
4140: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
4150: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
4160: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
4170: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
4180: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
4190: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
41a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
41b0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
41c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
41d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
41e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
41f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
4200: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
4210: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
4220: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
4230: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
4240: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
4250: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
4260: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
4270: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
4280: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
4290: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
42a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
42b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
42c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
42d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
42e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
42f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
4300: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
4310: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
4320: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
4330: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
4340: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
4350: 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  LL sqlite3_threa
4360: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
4370: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
4380: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
4390: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
43a0: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
43b0: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
43c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
43d0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
43e0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
43f0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
4400: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
4410: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
4420: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
4430: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
4440: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
4450: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
4460: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
4470: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
4480: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
4490: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
44a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
44b0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
44c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
44d0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
44e0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
44f0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
4500: 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  e()].** and [sql
4510: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d  ite3_close_v2()]
4520: 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63   are its destruc
4530: 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65  tors.  There are
4540: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69   many other.** i
4550: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20  nterfaces (such 
4560: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  as.** [sqlite3_p
4570: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
4580: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
4590: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
45a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
45b0: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
45c0: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
45d0: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
45e0: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20  n an.** sqlite3 
45f0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
4600: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
4610: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a  3 sqlite3;../*.*
4620: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42  * CAPI3REF: 64-B
4630: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73  it Integer Types
4640: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
4650: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
4660: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
4670: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
4680: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
4690: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
46a0: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
46b0: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
46c0: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
46d0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
46e0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
46f0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
4700: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
4710: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
4720: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
4730: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66  eferred type def
4740: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  initions..** The
4750: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
4760: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
4770: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72  types are suppor
4780: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
4790: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
47a0: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ty only..**.** ^
47b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
47c0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74  4 and sqlite_int
47d0: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
47e0: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
47f0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32  s.** between -92
4800: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
4810: 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33  8 and +922337203
4820: 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75  6854775807 inclu
4830: 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  sive.  ^The.** s
4840: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e  qlite3_uint64 an
4850: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
4860: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
4870: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a  integer values .
4880: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
4890: 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39   +18446744073709
48a0: 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65  551615 inclusive
48b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
48c0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
48d0: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
48e0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
48f0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
4900: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
4910: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
4920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
4930: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
4940: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
4950: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
4960: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
4970: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
4980: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
4990: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
49a0: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
49b0: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
49c0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
49d0: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
49e0: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
49f0: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
4a00: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
4a10: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
4a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
4a30: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
4a40: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
4a50: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
4a60: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
4a70: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
4a80: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
4a90: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
4aa0: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
4ab0: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
4ac0: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
4ad0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
4ae0: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
4af0: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
4b00: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
4b10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4b20: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
4b30: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
4b40: 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c   DESTRUCTOR: sql
4b50: 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
4b60: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
4b70: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
4b80: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20  e_v2() routines 
4b90: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a  are destructors.
4ba0: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  ** for the [sqli
4bb0: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
4bc0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
4bd0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
4be0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
4bf0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
4c00: 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73  OK] if.** the [s
4c10: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69  qlite3] object i
4c20: 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64  s successfully d
4c30: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
4c40: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72   associated.** r
4c50: 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61  esources are dea
4c60: 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  llocated..**.** 
4c70: 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
4c80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61   connection is a
4c90: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75  ssociated with u
4ca0: 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61  nfinalized prepa
4cb0: 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
4cc0: 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  s or unfinished 
4cd0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f  sqlite3_backup o
4ce0: 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69  bjects then sqli
4cf0: 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77  te3_close().** w
4d00: 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61  ill leave the da
4d10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4d20: 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72  n open and retur
4d30: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
4d40: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
4d50: 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61  close_v2() is ca
4d60: 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  lled with unfina
4d70: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73  lized prepared s
4d80: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64  tatements.** and
4d90: 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73  /or unfinished s
4da0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20  qlite3_backups, 
4db0: 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
4dc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63  e connection bec
4dd0: 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61  omes.** an unusa
4de0: 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69  ble "zombie" whi
4df0: 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  ch will automati
4e00: 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63  cally be dealloc
4e10: 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a  ated when the.**
4e20: 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73   last prepared s
4e30: 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61  tatement is fina
4e40: 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73  lized or the las
4e50: 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  t sqlite3_backup
4e60: 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e   is.** finished.
4e70: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c    The sqlite3_cl
4e80: 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ose_v2() interfa
4e90: 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ce is intended f
4ea0: 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68  or use with.** h
4eb0: 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68  ost languages th
4ec0: 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63  at are garbage c
4ed0: 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68  ollected, and wh
4ee0: 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e  ere the order in
4ef0: 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75   which.** destru
4f00: 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64  ctors are called
4f10: 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
4f20: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
4f30: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
4f40: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
4f50: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
4f60: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
4f70: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  ,.** [sqlite3_bl
4f80: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
4f90: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
4fa0: 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73  les], and .** [s
4fb0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69  qlite3_backup_fi
4fc0: 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61  nish | finish] a
4fd0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ll [sqlite3_back
4fe0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f  up] objects asso
4ff0: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
5000: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
5010: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
5020: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
5030: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
5040: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
5050: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
5060: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
5070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
5080: 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f  t still has.** o
5090: 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70  utstanding [prep
50a0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
50b0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
50c0: 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c  , and/or.** [sql
50d0: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
50e0: 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74  ects then it ret
50f0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
5100: 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63   and the dealloc
5110: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f  ation.** of reso
5120: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65  urces is deferre
5130: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65  d until all [pre
5140: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
5150: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
5160: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
5170: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
5180: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74  ts are also dest
5190: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  royed..**.** ^If
51a0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
51b0: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
51c0: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
51d0: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
51e0: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
51f0: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
5200: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
5210: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
5220: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
5230: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20  3_close(C)] and 
5240: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
5250: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  2(C)].** must be
5260: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
5270: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
5280: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
5290: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
52a0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
52b0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
52c0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
52d0: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
52e0: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
52f0: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
5300: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  osed..** ^Callin
5310: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
5320: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ) or sqlite3_clo
5330: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e  se_v2() with a N
5340: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61  ULL pointer.** a
5350: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72  rgument is a har
5360: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
5370: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
5380: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
5390: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
53a0: 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
53b0: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
53c0: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f  CALL sqlite3_clo
53d0: 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b  se_v2(sqlite3*);
53e0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
53f0: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
5400: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
5410: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
5420: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
5430: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
5440: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
5450: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
5460: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
5470: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
5480: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
5490: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
54a0: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
54b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
54c0: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
54d0: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
54e0: 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  face.** METHOD: 
54f0: 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
5500: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
5510: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
5520: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
5530: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
5540: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
5550: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
5560: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
5570: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
5580: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
5590: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
55a0: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
55b0: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
55c0: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
55d0: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
55e0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
55f0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
5600: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
5610: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
5620: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
5630: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
5640: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
5650: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
5660: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
5670: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
5680: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
5690: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
56a0: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
56b0: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
56c0: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
56d0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
56e0: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
56f0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
5700: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
5710: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
5720: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
5730: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
5740: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
5750: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
5760: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
5770: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
5780: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
5790: 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20  ec() is relayed 
57a0: 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31  through to the 1
57b0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65  st argument of e
57c0: 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ach.** callback 
57d0: 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66  invocation.  ^If
57e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f   the callback po
57f0: 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
5800: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55  _exec().** is NU
5810: 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c  LL, then no call
5820: 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76  back is ever inv
5830: 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20  oked and result 
5840: 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f  rows are.** igno
5850: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  red..**.** ^If a
5860: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
5870: 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
5880: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
5890: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  ts passed into.*
58a0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
58b0: 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e  , then execution
58c0: 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
58d0: 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20  statement stops 
58e0: 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  and.** subsequen
58f0: 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  t statements are
5900: 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74   skipped.  ^If t
5910: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
5920: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
5930: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ().** is not NUL
5940: 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72  L then any error
5950: 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74   message is writ
5960: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
5970: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
5980: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
5990: 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62  ()] and passed b
59a0: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20  ack through the 
59b0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  5th parameter..*
59c0: 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72  * To avoid memor
59d0: 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70  y leaks, the app
59e0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
59f0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
5a00: 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72  free()].** on er
5a10: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
5a20: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72  ngs returned thr
5a30: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
5a40: 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20  ameter of.** of 
5a50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
5a60: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
5a70: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
5a80: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
5a90: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
5aa0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
5ab0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
5ac0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
5ad0: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
5ae0: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
5af0: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
5b00: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
5b10: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
5b20: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
5b30: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
5b40: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
5b50: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
5b60: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
5b70: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
5b80: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
5b90: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
5ba0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
5bb0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
5bc0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
5bd0: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
5be0: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
5bf0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
5c00: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
5c10: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
5c20: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
5c30: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
5c40: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
5c50: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
5c60: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
5c70: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to 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 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
5ca0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
5cb0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
5cc0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
5cd0: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
5ce0: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
5cf0: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
5d00: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
5d10: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
5d20: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
5d30: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
5d40: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
5d50: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
5d60: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
5d70: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
5d80: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
5d90: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
5da0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
5db0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
5dc0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
5dd0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
5de0: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
5df0: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
5e00: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
5e10: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
5e20: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
5e30: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
5e40: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
5e50: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
5e60: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
5e70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
5e80: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
5e90: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
5ea0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
5eb0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
5ec0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
5ed0: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
5ee0: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
5ef0: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
5f00: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
5f10: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
5f20: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
5f30: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
5f40: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
5f50: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
5f60: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
5f70: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
5f80: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  st insure that t
5f90: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
5fa0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
5fb0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
5fc0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
5fd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5fe0: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
5ff0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
6000: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
6010: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
6020: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
6030: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
6040: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
6050: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
6060: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
6070: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
6080: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
6090: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
60a0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
60b0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
60c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
60d0: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
60e0: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
60f0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
6100: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
6110: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
6120: 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
6130: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
6140: 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  LL sqlite3_exec(
6150: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
6160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
6180: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
6190: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
61a0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
61b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61c0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
61d0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
61e0: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
61f0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
6200: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
6210: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
6220: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
6250: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
6260: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
6270: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6290: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
62a0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
62b0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
62c0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
62d0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
62e0: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
62f0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
6300: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
6310: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
6320: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
6330: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
6340: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
6350: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
6360: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73  indicate success
6370: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
6380: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
6390: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
63a0: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
63b0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
63c0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65  .** See also: [e
63d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
63e0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d  ode definitions]
63f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6400: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
6410: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
6420: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
6430: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
6440: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
6460: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
6470: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
6480: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
6490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
64a0: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
64b0: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
64c0: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
64f0: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
6500: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
6510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6520: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
6530: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
6540: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
6550: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
6560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
6570: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
6580: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
6590: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
65a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
65b0: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
65c0: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
65d0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
65e0: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
65f0: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
6600: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
6610: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
6620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
6630: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
6640: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
6650: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
6660: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
6670: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
6680: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
6690: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
66a0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
66b0: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
66c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
66d0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
66e0: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
66f0: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
6700: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6710: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
6720: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
6730: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
6740: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
6750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6760: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
6770: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
6780: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
6790: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
67a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
67b0: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
67c0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
67d0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
67e0: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
67f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6800: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
6810: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
6820: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
6830: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
6840: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
6850: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
6860: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
6870: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
6880: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
6890: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
68a0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
68b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
68c0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
68d0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
68e0: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
6910: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
6920: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
6930: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6950: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
6960: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
6970: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
6980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6990: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
69a0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
69b0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
69c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
69d0: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
69e0: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
69f0: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
6a10: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
6a20: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
6a30: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
6a40: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
6a50: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
6a60: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
6a70: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
6a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6a90: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
6aa0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
6ab0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
6ac0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
6ad0: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
6ae0: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
6af0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
6b00: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
6b10: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
6b20: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
6b30: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
6b40: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
6b50: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
6b60: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
6b70: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20   SQLITE_NOTICE  
6b80: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69      27   /* Noti
6b90: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73  fications from s
6ba0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
6bb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
6bc0: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20  ARNING     28   
6bd0: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d  /* Warnings from
6be0: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
6bf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6c00: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
6c10: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
6c20: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
6c30: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
6c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
6c50: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
6c60: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
6c70: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
6c80: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
6c90: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
6ca0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6cb0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
6cc0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
6cd0: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
6ce0: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
6cf0: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49  nitions}.**.** I
6d00: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
6d10: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
6d20: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
6d30: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33   return one of 3
6d40: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65  0 integer.** [re
6d50: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
6d60: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
6d70: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
6d80: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
6d90: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
6da0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
6db0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
6dc0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
6dd0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
6de0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
6df0: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
6e00: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
6e10: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
6e20: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
6e30: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
6e40: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
6e50: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
6e60: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
6e70: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
6e80: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
6e90: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
6ea0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
6eb0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
6ec0: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
6ed0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
6ee0: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
6ef0: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
6f00: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
6f10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
6f20: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
6f30: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
6f40: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
6f50: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
6f60: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
6f70: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
6f80: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
6f90: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
6fa0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
6fb0: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
6fc0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
6fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
6fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
6ff0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7000: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7010: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7020: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
7030: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
7040: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7050: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
7060: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
7070: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
7080: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7090: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
70a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
70b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
70c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
70d0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
70e0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
70f0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
7100: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7110: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
7120: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7130: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
7140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7150: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
7160: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7170: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
7180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7190: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
71a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
71b0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
71c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71d0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
71e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
71f0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
7200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7210: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
7220: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7230: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
7240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7250: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
7260: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7270: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
7280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7290: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
72a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
72b0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
72c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
72d0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
72e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
72f0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
7300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7310: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
7320: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
7330: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
7340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7350: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
7360: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7370: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
7380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7390: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
73a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
73b0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
73c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
73d0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
73e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
73f0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
7400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7410: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
7420: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7430: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
7440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7450: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
7460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7470: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
7480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7490: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
74a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
74b0: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
74c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
74d0: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
74e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
74f0: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
7500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7510: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
7520: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7530: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
7540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7550: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
7560: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7570: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
7580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7590: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
75a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
75b0: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
75c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
75d0: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
75e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
75f0: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
7600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7610: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
7620: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7630: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
7640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7650: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
7660: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
7670: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
7680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
7690: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
76a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
76b0: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
76c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
76d0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
76e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
76f0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
7700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7710: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
7720: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
7730: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
7740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7750: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
7760: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7770: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
7780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7790: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
77a0: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
77b0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
77c0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
77d0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
77e0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
77f0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
7800: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
7810: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
7820: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
7830: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
7840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
7850: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
7860: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
7870: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
7880: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
7890: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
78a0: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
78b0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
78c0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
78d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
78e0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
78f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7900: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
7910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
7920: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
7930: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
7940: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
7950: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7960: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
7970: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7980: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
7990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79a0: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
79b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
79c0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
79d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
79e0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
79f0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
7a00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7a10: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7a20: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7a30: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
7a40: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7a50: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
7a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7a70: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
7a80: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7a90: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
7aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7ab0: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
7ac0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
7ad0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
7ae0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7af0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
7b00: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
7b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7b20: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
7b30: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7b40: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
7b50: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7b60: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
7b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7b80: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
7b90: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7ba0: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
7bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7bc0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
7bd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7be0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
7bf0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7c00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
7c10: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
7c20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7c30: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
7c40: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
7c50: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
7c60: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
7c70: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
7c80: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
7c90: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
7ca0: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
7cb0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7cc0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
7cd0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
7ce0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
7cf0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
7d00: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
7d10: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
7d20: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
7d30: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
7d40: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
7d50: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
7d60: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
7d70: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
7d80: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
7d90: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
7da0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
7db0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
7dc0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
7dd0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
7de0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
7df0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7e00: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
7e10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7e20: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
7e30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7e40: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
7e50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7e60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7e70: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7e80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7e90: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
7ea0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7eb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7ec0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
7ed0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7ee0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
7ef0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
7f00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7f10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7f20: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
7f30: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
7f40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7f50: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7f60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7f70: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
7f80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7f90: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
7fa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7fb0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
7fc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7fd0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
7fe0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7ff0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
8000: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
8010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8020: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
8030: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
8040: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
8050: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
8060: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8070: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
8080: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
8090: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
80a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
80b0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
80c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
80d0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
80e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
80f0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
8100: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
8110: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
8120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8130: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
8140: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
8150: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
8160: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8170: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
8180: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
8190: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
81a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
81b0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
81c0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
81d0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
81e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
81f0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
8200: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
8210: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
8220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8230: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
8240: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
8250: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
8260: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
8270: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8280: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
8290: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
82a0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
82b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
82c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
82d0: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
82e0: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
82f0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
8300: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
8310: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8320: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
8330: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
8340: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
8350: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
8360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8370: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
8380: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
8390: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
83a0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
83b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
83c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
83d0: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
83e0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
83f0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
8400: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
8410: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
8420: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
8430: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8440: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
8450: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
8460: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
8470: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
8480: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
8490: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
84a0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
84b0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
84c0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
84d0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
84e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
84f0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
8500: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
8510: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8520: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8530: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8540: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8550: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8560: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8570: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8580: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8590: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
85a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
85b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
85c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
85d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
85e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
85f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8600: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8610: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8620: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8630: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8640: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8650: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8660: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8670: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8680: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8690: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
86a0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
86b0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
86c0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
86d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
86e0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
86f0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8700: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8710: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8720: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8730: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8740: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
8750: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
8760: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
8770: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
8780: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
8790: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
87a0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
87b0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
87c0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
87d0: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
87e0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
87f0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
8800: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
8810: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
8820: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
8830: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
8840: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
8850: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
8860: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
8870: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
8880: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
8890: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
88a0: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
88b0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
88c0: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
88d0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
88e0: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
88f0: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
8900: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
8910: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
8920: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
8930: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
8940: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
8950: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
8960: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
8970: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8980: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
8990: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
89a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
89b0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
89c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
89d0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
89e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
89f0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
8a00: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
8a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8a20: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
8a30: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8a40: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8a60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8a70: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
8a80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8a90: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
8aa0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
8ab0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
8ac0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
8ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8ae0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
8af0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8b00: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
8b10: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
8b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8b30: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
8b40: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8b50: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
8b60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b70: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
8b80: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
8b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8ba0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
8bb0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8bc0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
8bd0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
8be0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
8bf0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
8c00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8c10: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
8c20: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
8c30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8c40: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
8c50: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
8c60: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
8c70: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
8c80: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
8c90: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
8ca0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
8cb0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
8cc0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
8cd0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
8ce0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
8cf0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
8d00: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
8d10: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
8d20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8d30: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
8d40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
8d50: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
8d60: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
8d70: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
8d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8d90: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
8da0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
8db0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
8dc0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
8dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8de0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
8df0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
8e00: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
8e10: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
8e20: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
8e30: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
8e40: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
8e50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8e60: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
8e70: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
8e80: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
8e90: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
8ea0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
8eb0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
8ec0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
8ed0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
8ee0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
8ef0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
8f00: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
8f10: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
8f20: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
8f30: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
8f40: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
8f50: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
8f60: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
8f70: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
8f80: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
8f90: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
8fa0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
8fb0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
8fc0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
8fd0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
8fe0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
8ff0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
9000: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
9010: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
9020: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
9030: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
9040: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
9050: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
9060: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
9070: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
9080: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
9090: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
90a0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
90b0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
90c0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
90d0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
90e0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
90f0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
9100: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
9110: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
9120: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
9130: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
9140: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
9150: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
9160: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
9170: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
9180: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
9190: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
91a0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
91b0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
91c0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
91d0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
91e0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
91f0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
9200: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
9210: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
9220: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
9230: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
9240: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
9250: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
9260: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
9270: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
9280: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
9290: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
92a0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
92b0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
92c0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
92d0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
92e0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
92f0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
9300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9310: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
9320: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
9330: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
9340: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
9350: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
9360: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
9370: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
9380: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9390: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
93a0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
93b0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
93c0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
93d0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
93e0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
93f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
9400: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
9410: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
9420: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
9430: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
9440: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
9450: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
9460: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
9470: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
9480: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
9490: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
94a0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
94b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
94c0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
94d0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
94e0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
94f0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
9500: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
9510: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
9520: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
9530: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
9540: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
9550: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
9560: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
9570: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
9580: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
9590: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
95a0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
95b0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
95c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
95d0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
95e0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
95f0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
9600: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
9610: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
9620: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
9630: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
9640: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9650: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
9660: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
9670: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
9680: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9690: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
96a0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
96b0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
96c0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
96d0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
96e0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
96f0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
9700: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
9710: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
9720: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
9730: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
9740: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
9750: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
9760: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
9770: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
9780: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
9790: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
97a0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
97b0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
97c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
97d0: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
97e0: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
97f0: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
9800: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
9810: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
9820: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
9830: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
9840: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
9850: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
9860: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
9870: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
9880: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
9890: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
98a0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
98b0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
98c0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
98d0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
98e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
98f0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
9900: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
9910: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
9920: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
9930: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
9940: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
9950: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
9960: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
9970: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
9980: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
9990: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
99a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
99b0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
99c0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
99d0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
99e0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
99f0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
9a00: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
9a10: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
9a20: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
9a30: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
9a40: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
9a50: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
9a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9a70: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
9a80: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
9a90: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
9aa0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
9ab0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
9ac0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
9ad0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
9ae0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
9af0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
9b00: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
9b10: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
9b20: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
9b30: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9b40: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
9b50: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
9b60: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
9b70: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
9b80: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
9b90: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
9ba0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
9bb0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
9bc0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
9bd0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
9be0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
9bf0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
9c00: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
9c10: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
9c20: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
9c30: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
9c40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
9c50: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
9c60: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
9c70: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
9c80: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
9c90: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
9ca0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
9cb0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
9cc0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
9cd0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9ce0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
9cf0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
9d00: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
9d10: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
9d20: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
9d30: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
9d40: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
9d50: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
9d60: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
9d70: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
9d80: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
9d90: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
9da0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
9db0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
9dc0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
9dd0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
9de0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
9df0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
9e00: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
9e10: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
9e20: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
9e30: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
9e40: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
9e50: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
9e60: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
9e70: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
9e80: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
9e90: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
9ea0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
9eb0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
9ec0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
9ed0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
9ee0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
9ef0: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
9f00: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
9f10: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
9f20: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
9f30: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
9f40: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
9f50: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
9f60: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9f70: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
9f80: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
9f90: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
9fa0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
9fb0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
9fc0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
9fd0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
9fe0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
9ff0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
a000: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
a010: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
a020: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
a030: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
a040: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
a050: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
a060: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
a070: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
a080: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
a090: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
a0a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
a0b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
a0c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
a0d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
a0e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
a0f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
a100: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
a110: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
a120: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
a130: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
a140: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
a150: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
a160: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
a170: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a180: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
a190: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a1a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
a1b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a1c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
a1d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a1e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
a1f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a200: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
a210: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a220: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
a230: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a240: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
a250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a260: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
a270: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a280: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
a290: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
a2a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
a2b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
a2c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
a2d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
a2e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a2f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
a300: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
a310: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
a320: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
a330: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
a340: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
a350: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
a360: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
a370: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
a380: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
a390: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
a3a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
a3b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
a3c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
a3d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
a3e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
a3f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
a400: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
a410: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
a420: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
a430: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
a440: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
a450: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
a460: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
a470: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
a480: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
a490: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
a4a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
a4b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
a4c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
a4d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
a4e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
a4f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
a500: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
a510: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
a520: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
a530: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
a540: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
a550: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
a560: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
a570: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
a580: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
a590: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
a5a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
a5b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
a5c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
a5d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
a5e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
a5f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
a600: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
a610: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
a620: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
a630: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
a640: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
a650: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a660: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
a670: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
a680: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
a690: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
a6a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a6b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
a6c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
a6d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
a6e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
a6f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
a700: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
a710: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
a720: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
a730: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
a740: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
a750: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
a760: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
a770: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
a780: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
a790: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
a7a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
a7b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
a7c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
a7d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
a7e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
a7f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
a800: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
a810: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
a820: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
a830: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
a840: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
a850: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
a860: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
a870: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
a880: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
a890: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
a8a0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
a8b0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a8c0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
a8d0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
a8e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
a8f0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
a900: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
a910: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
a920: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
a930: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
a940: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
a950: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
a960: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
a970: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
a980: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
a990: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
a9a0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
a9b0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
a9c0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
a9d0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
a9e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a9f0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
aa00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
aa10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
aa20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
aa30: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
aa40: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
aa50: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
aa60: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
aa70: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
aa80: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
aa90: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
aaa0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
aab0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
aac0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
aad0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
aae0: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
aaf0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
ab00: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
ab10: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
ab20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ab30: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
ab40: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
ab50: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
ab60: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
ab70: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
ab80: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
ab90: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
aba0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
abb0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
abc0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
abd0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
abe0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
abf0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
ac00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
ac10: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
ac20: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
ac30: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
ac40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
ac50: 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  TATE]].** The [S
ac60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
ac70: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
ac80: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
ac90: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
aca0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
acb0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
acc0: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
acd0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
ace0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
acf0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
ad00: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
ad10: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
ad20: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
ad30: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
ad40: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
ad50: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
ad60: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
ad70: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
ad80: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
ad90: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
ada0: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
adb0: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
adc0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
add0: 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
ade0: 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49  le when the SQLI
adf0: 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69  TE_TEST.** compi
ae00: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
ae10: 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  s used..**.** <l
ae20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ae30: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
ae40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ae50: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
ae60: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
ae70: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
ae80: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
ae90: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
aea0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
aeb0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
aec0: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
aed0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
aee0: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
aef0: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
af00: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
af10: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
af20: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
af30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
af40: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
af50: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
af60: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
af70: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
af80: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
af90: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
afa0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
afb0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
afc0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
afd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
afe0: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
aff0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
b000: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
b010: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
b020: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
b030: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
b040: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
b050: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
b060: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
b070: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
b080: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
b090: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
b0a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
b0b0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
b0c0: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
b0d0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
b0e0: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
b0f0: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
b100: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
b110: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
b120: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
b130: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
b140: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
b150: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
b160: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
b170: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
b180: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
b190: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
b1a0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
b1b0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
b1c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b1e0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
b1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
b200: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
b210: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
b220: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
b230: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
b240: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
b250: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
b260: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
b270: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
b280: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
b290: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
b2a0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
b2b0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
b2c0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
b2d0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
b2e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
b2f0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
b300: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
b310: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b320: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
b330: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b340: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
b350: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
b360: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
b370: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
b380: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
b390: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
b3a0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
b3b0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
b3c0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
b3d0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
b3e0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
b3f0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
b400: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
b410: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
b420: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
b430: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
b440: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
b450: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
b460: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
b470: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
b480: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
b490: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
b4a0: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
b4b0: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
b4c0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
b4d0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
b4e0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
b4f0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b500: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
b510: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
b520: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
b530: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
b540: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
b550: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
b560: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
b570: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
b580: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
b590: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
b5a0: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
b5b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
b5c0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
b5d0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
b5e0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
b5f0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
b600: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
b610: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
b620: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
b630: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
b640: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
b650: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
b660: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
b670: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
b680: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
b690: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b6a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
b6b0: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
b6c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
b6d0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
b6e0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
b6f0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
b700: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
b710: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
b720: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
b730: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
b740: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
b750: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
b760: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
b770: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
b780: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
b790: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
b7a0: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
b7b0: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
b7c0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
b7d0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
b7e0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
b7f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
b800: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
b810: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
b820: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
b830: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
b840: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
b850: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
b860: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
b870: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b880: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
b890: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b8a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b8b0: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
b8c0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
b8d0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
b8e0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
b8f0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
b900: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
b910: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
b920: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
b930: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
b940: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
b950: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
b960: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
b970: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
b980: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
b990: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
b9a0: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
b9b0: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
b9c0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
b9d0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
b9e0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
b9f0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
ba00: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
ba10: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
ba20: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
ba30: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
ba40: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
ba50: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
ba60: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
ba70: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
ba80: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
ba90: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
baa0: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
bab0: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
bac0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
bad0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
bae0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
baf0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
bb00: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
bb10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
bb20: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
bb30: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
bb40: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
bb50: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
bb60: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
bb70: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
bb80: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
bb90: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
bba0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
bbb0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
bbc0: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
bbd0: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
bbe0: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
bbf0: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
bc00: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
bc10: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
bc20: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
bc30: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
bc40: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
bc50: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
bc60: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
bc70: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
bc80: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
bc90: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
bca0: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
bcb0: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
bcc0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bcd0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
bce0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
bcf0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bd00: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
bd10: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
bd20: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
bd30: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
bd40: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
bd50: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
bd60: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
bd70: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
bd80: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
bd90: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
bda0: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
bdb0: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
bdc0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
bdd0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
bde0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
bdf0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
be00: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
be10: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
be20: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
be30: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
be40: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
be50: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
be60: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
be70: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
be80: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
be90: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
bea0: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
beb0: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
bec0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
bed0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
bee0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
bef0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
bf00: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
bf10: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
bf20: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
bf30: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
bf40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
bf50: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
bf60: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
bf70: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
bf80: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
bf90: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
bfa0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
bfb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bfc0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
bfd0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
bfe0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
bff0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
c000: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
c010: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
c020: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
c030: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
c040: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
c050: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
c060: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
c070: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
c080: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c0a0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
c0b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c0c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
c0d0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
c0e0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
c0f0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
c100: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
c110: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
c120: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
c130: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
c140: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
c150: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
c160: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
c170: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
c180: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
c190: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
c1a0: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
c1b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
c1c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
c1d0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
c1e0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
c1f0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
c200: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
c210: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
c220: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
c230: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
c240: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
c250: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
c260: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
c270: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
c280: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
c290: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
c2a0: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
c2b0: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
c2c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c2d0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
c2e0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c2f0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
c300: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
c310: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
c320: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
c330: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
c340: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
c350: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
c360: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
c370: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
c380: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
c390: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
c3a0: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
c3b0: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
c3c0: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
c3d0: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
c3e0: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
c3f0: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
c400: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
c410: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
c420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
c430: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
c440: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
c450: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
c460: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
c470: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
c480: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
c490: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
c4a0: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
c4b0: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
c4c0: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
c4d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
c4e0: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
c4f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
c500: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
c510: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
c520: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
c530: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
c540: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
c550: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c560: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
c570: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
c580: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
c590: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
c5a0: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
c5b0: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
c5c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
c5d0: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
c5e0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
c5f0: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
c600: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
c610: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
c620: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
c630: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
c640: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
c650: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
c660: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
c670: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
c680: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
c690: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
c6a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
c6b0: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
c6c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c6d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
c6e0: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
c6f0: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
c700: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
c710: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
c720: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
c730: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
c740: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
c750: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
c760: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
c770: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
c780: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
c790: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
c7a0: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
c7b0: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
c7c0: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
c7d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
c7e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
c7f0: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
c800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
c810: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
c820: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
c830: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
c840: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
c850: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
c860: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
c870: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
c880: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
c890: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
c8a0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
c8b0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
c8c0: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
c8d0: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
c8e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
c8f0: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
c900: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
c910: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
c920: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
c930: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
c940: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
c950: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
c960: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
c970: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
c980: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
c990: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
c9a0: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
c9b0: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
c9c0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
c9d0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
c9e0: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
c9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ca00: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ca10: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
ca20: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
ca30: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
ca40: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
ca50: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
ca60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ca70: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
ca80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ca90: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
caa0: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
cab0: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
cac0: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
cad0: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
cae0: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
caf0: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
cb00: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
cb10: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20  ed statement if 
cb20: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73  result string is
cb30: 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72   NULL, or that r
cb40: 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a  eturns a copy.**
cb50: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
cb60: 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72  tring if the str
cb70: 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e  ing is non-NULL.
cb80: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
cb90: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
cba0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
cbb0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
cbc0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
cbd0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
cbe0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
cbf0: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
cc00: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
cc10: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
cc20: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
cc30: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
cc40: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
cc50: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
cc60: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
cc70: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
cc80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cc90: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
cca0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
ccb0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
ccc0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
ccd0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
cce0: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
ccf0: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
cd00: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
cd10: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
cd20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cd30: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
cd40: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
cd50: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
cd60: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
cd70: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
cd80: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
cd90: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
cda0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
cdb0: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
cdc0: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
cdd0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
cde0: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
cdf0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
ce00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
ce10: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
ce20: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
ce30: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
ce40: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
ce50: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
ce60: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
ce70: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
ce80: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
ce90: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
cea0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
ceb0: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
cec0: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
ced0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
cee0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
cef0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
cf00: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
cf10: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
cf20: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
cf30: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
cf40: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
cf50: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
cf60: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
cf70: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
cf80: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
cf90: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
cfa0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
cfb0: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
cfc0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
cfd0: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
cfe0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cff0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
d000: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
d010: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
d020: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d030: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
d040: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
d050: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
d060: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
d070: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
d080: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
d090: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
d0a0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
d0b0: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
d0c0: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
d0d0: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
d0e0: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
d0f0: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
d100: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
d110: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
d120: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
d130: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
d140: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
d150: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
d160: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
d170: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
d180: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
d190: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
d1a0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
d1b0: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
d1c0: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
d1d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d1e0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
d1f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d200: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
d210: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
d220: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
d230: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
d240: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
d250: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
d260: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
d270: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
d280: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
d290: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
d2a0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
d2b0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
d2c0: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
d2d0: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
d2e0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
d2f0: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
d300: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
d310: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
d320: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
d330: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
d340: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
d350: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
d360: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
d370: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
d380: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
d390: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
d3a0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
d3b0: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
d3c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
d3d0: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
d3e0: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
d3f0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
d400: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
d410: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
d420: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
d430: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d440: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
d450: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d460: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
d470: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
d480: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
d490: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
d4a0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
d4b0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
d4c0: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
d4d0: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
d4e0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
d4f0: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
d500: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
d510: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
d520: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
d530: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
d540: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
d550: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
d560: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
d570: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
d580: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
d590: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
d5a0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
d5b0: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
d5c0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
d5d0: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
d5e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d5f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
d600: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
d610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
d620: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
d630: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
d640: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
d650: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
d660: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
d670: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
d680: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
d690: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
d6a0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
d6b0: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
d6c0: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
d6d0: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
d6e0: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
d6f0: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
d700: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d710: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
d720: 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20  HANDLE]].** The 
d730: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
d740: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20  N32_SET_HANDLE] 
d750: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
d760: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
d770: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
d780: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
d790: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
d7a0: 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61  swap the file ha
d7b0: 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e  ndle with the on
d7c0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  e.** pointed to 
d7d0: 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75  by the pArg argu
d7e0: 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61  ment.  This capa
d7f0: 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64  bility is used d
d800: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a  uring testing.**
d810: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
d820: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
d830: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
d840: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a   is defined..**.
d850: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d860: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d  FCNTL_WAL_BLOCK]
d870: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
d880: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
d890: 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  ] is a signal to
d8a0: 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74   the VFS layer t
d8b0: 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20  hat it might.** 
d8c0: 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20  be advantageous 
d8d0: 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  to block on the 
d8e0: 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66  next WAL lock if
d8f0: 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74   the lock is not
d900: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
d910: 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20  available.  The 
d920: 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73  WAL subsystem is
d930: 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c  sues this signal
d940: 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20   during rare.** 
d950: 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e  circumstances in
d960: 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20   order to fix a 
d970: 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69  problem with pri
d980: 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e  ority inversion.
d990: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
d9a0: 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c   should <em>not<
d9b0: 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69  /em> use this fi
d9c0: 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a  le-control..**.*
d9d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d9e0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
d9f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
da00: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
da10: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
da20: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
da30: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
da40: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
da50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
da60: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
da70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
da80: 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 41 5d 5d 0a  ITE_FCNTL_OTA]].
da90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
daa0: 43 4e 54 4c 5f 4f 54 41 5d 20 6f 70 63 6f 64 65  CNTL_OTA] opcode
dab0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
dac0: 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  by the special V
dad0: 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68  FS used by.** th
dae0: 65 20 4f 54 41 20 65 78 74 65 6e 73 69 6f 6e 20  e OTA extension 
daf0: 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72  only.  All other
db00: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
db10: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
db20: 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f  ND for.** this o
db30: 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c  pcode.  .** </ul
db40: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
db60: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
db70: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
db90: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
dba0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
dbc0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
dbd0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
dbf0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
dc20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc40: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
dc50: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc70: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
dc80: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dca0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
dcb0: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcd0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
dce0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
dcf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dd00: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
dd10: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
dd20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dd30: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
dd40: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
dd50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
dd60: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
dd70: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
dd80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
dd90: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
dda0: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
ddb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ddc0: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
ddd0: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
dde0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
ddf0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
de00: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
de10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
de20: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
de30: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
de40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
de50: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
de60: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
de70: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
de80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
de90: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
dea0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
deb0: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
dec0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
ded0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
dee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
def0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
df00: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
df10: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
df20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
df30: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
df40: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
df50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
df60: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
df70: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64             24.#d
df80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
df90: 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20  TL_ZIPVFS       
dfa0: 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65            25.#de
dfb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dfc0: 4c 5f 4f 54 41 20 20 20 20 20 20 20 20 20 20 20  L_OTA           
dfd0: 20 20 20 20 20 20 20 20 20 32 36 0a 0a 2f 2a 20           26../* 
dfe0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dff0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e000: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
e010: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
e020: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
e030: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
e040: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
e050: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
e060: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
e070: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
e080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
e090: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
e0a0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
e0b0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
e0c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
e0d0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
e0e0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
e0f0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
e100: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
e110: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
e120: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
e130: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
e140: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
e150: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
e160: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
e170: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
e180: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
e190: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
e1a0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
e1b0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
e1c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
e1d0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
e1e0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
e1f0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
e200: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
e210: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
e220: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
e230: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
e240: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
e250: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
e260: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
e270: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
e280: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
e290: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
e2a0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
e2b0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
e2c0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
e2d0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
e2e0: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
e2f0: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
e300: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
e310: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
e320: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
e330: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
e340: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
e350: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
e360: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
e370: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
e380: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
e390: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
e3a0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
e3b0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
e3c0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
e3d0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
e3e0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
e3f0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
e400: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
e410: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
e420: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
e430: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
e440: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
e450: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
e460: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
e470: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
e480: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
e490: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
e4a0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
e4b0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
e4c0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
e4d0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
e4e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
e4f0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
e500: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
e510: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
e520: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
e530: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
e540: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
e550: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
e560: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
e570: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
e580: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
e590: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
e5a0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
e5b0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
e5c0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
e5d0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
e5e0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
e5f0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
e600: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
e610: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
e620: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
e630: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
e640: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
e650: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
e660: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
e670: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
e680: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
e690: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
e6a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
e6b0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
e6c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e6d0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
e6e0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
e6f0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
e700: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
e710: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
e720: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
e730: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
e740: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
e750: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
e760: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
e770: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
e780: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
e790: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
e7a0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
e7b0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e7c0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
e7d0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
e7e0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
e7f0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
e800: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
e810: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
e820: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
e830: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
e840: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
e850: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
e860: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
e870: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
e880: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
e890: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
e8a0: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
e8b0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
e8c0: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
e8d0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
e8e0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
e8f0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
e900: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
e910: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
e920: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
e930: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
e940: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
e950: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
e960: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
e970: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
e980: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
e990: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
e9a0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
e9b0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
e9c0: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
e9d0: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
e9e0: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
e9f0: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
ea00: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
ea10: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
ea20: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
ea30: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
ea40: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
ea50: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
ea60: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
ea70: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
ea80: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
ea90: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
eaa0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
eab0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
eac0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
ead0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
eae0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
eaf0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
eb00: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
eb10: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
eb20: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
eb30: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
eb40: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
eb50: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
eb60: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
eb70: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
eb80: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
eb90: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
eba0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
ebb0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
ebc0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
ebd0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
ebe0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
ebf0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
ec00: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
ec10: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
ec20: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
ec30: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
ec40: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
ec50: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
ec60: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
ec70: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ec80: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
ec90: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
eca0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
ecb0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
ecc0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
ecd0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
ece0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
ecf0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
ed00: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
ed10: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
ed20: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
ed30: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
ed40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
ed50: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
ed60: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
ed70: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
ed80: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
ed90: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
eda0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
edb0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
edc0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
edd0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
ede0: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
edf0: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
ee00: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ee10: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
ee20: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ee30: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
ee40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ee50: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
ee60: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee70: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
ee80: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ee90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
eea0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
eeb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
eec0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
eed0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
eee0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
eef0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ef00: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
ef10: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
ef20: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
ef30: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
ef40: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
ef50: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
ef60: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
ef70: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
ef80: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
ef90: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
efa0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
efb0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
efc0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
efd0: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
efe0: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
eff0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
f000: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
f010: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
f020: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
f030: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
f040: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
f050: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
f060: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
f070: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
f080: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f090: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
f0a0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
f0b0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
f0c0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
f0d0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
f0e0: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
f0f0: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
f100: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
f110: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
f120: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
f130: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
f140: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
f150: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
f160: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
f170: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
f180: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
f190: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
f1a0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
f1b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
f1c0: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
f1d0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
f1e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f1f0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
f200: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
f210: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
f220: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
f230: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
f240: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f250: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
f260: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
f270: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
f280: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
f290: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
f2a0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
f2b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
f2c0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f2d0: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
f2e0: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
f2f0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
f300: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
f310: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
f320: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
f330: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
f340: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
f350: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
f360: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
f370: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
f380: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
f390: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
f3a0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
f3b0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
f3c0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
f3d0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
f3e0: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
f3f0: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
f400: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
f410: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
f420: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
f430: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
f440: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
f450: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
f460: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
f470: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
f480: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
f490: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
f4a0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
f4b0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
f4c0: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
f4d0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
f4e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
f4f0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
f500: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
f510: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
f520: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
f530: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
f540: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
f550: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
f560: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
f570: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
f580: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
f590: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
f5a0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
f5b0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
f5c0: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
f5d0: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
f5e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
f5f0: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
f600: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
f610: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
f620: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
f630: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
f640: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
f650: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
f660: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
f670: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
f680: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
f690: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
f6a0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
f6b0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
f6c0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
f6d0: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
f6e0: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
f6f0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
f700: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
f710: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
f720: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
f730: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
f740: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
f750: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f760: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
f770: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
f780: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
f790: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
f7a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f7b0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
f7c0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
f7d0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
f7e0: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
f7f0: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
f800: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
f810: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
f820: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
f830: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
f840: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
f850: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
f860: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
f870: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
f880: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
f890: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
f8a0: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
f8b0: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
f8c0: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
f8d0: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
f8e0: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
f8f0: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
f900: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
f910: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
f920: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
f930: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
f940: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
f950: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f960: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
f970: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
f980: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
f990: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
f9a0: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
f9b0: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
f9c0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
f9d0: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
f9e0: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
f9f0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
fa00: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
fa10: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
fa20: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
fa30: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
fa40: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
fa50: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
fa60: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
fa70: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
fa80: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
fa90: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
faa0: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
fab0: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
fac0: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
fad0: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
fae0: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
faf0: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
fb00: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
fb10: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
fb20: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
fb30: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
fb40: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
fb50: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
fb60: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
fb70: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
fb80: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
fb90: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
fba0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
fbb0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
fbc0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
fbd0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
fbe0: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
fbf0: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
fc00: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
fc10: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
fc20: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
fc30: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
fc40: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
fc50: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
fc60: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
fc70: 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
fc80: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
fc90: 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
fca0: 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
fcb0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
fcc0: 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
fcd0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
fce0: 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
fcf0: 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
fd00: 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
fd10: 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
fd20: 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
fd30: 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
fd40: 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
fd50: 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
fd60: 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
fd70: 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
fd80: 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
fd90: 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
fda0: 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
fdb0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
fdc0: 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
fdd0: 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
fde0: 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
fdf0: 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
fe00: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
fe10: 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
fe20: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
fe30: 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
fe40: 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
fe50: 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
fe60: 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
fe70: 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
fe80: 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
fe90: 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
fea0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
feb0: 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
fec0: 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
fed0: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
fee0: 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
fef0: 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
ff00: 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
ff10: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
ff20: 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
ff30: 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
ff40: 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
ff50: 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
ff60: 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
ff70: 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
ff80: 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
ff90: 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
ffa0: 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
ffb0: 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
ffc0: 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
ffd0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
ffe0: 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
fff0: 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
10000 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
10010 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
10020 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
10030 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
10040 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
10050 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
10060 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
10070 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
10080 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
10090 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
100a0 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
100b0 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
100c0 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
100d0 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
100e0 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
100f0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
10100 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
10110 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
10120 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
10130 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
10140 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
10150 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
10160 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
10170 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
10180 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
10190 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
101a0 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
101b0 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
101c0 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
101d0 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
101e0 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
101f0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
10200 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
10210 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
10220 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
10230 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
10240 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
10250 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10260 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
10270 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
10280 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
10290 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
102a0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
102b0 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
102c0 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
102d0 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
102e0 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
102f0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10300 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
10310 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
10320 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
10330 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
10340 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
10350 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10360 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10370 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
10380 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
10390 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
103a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
103b0 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
103c0 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
103d0 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
103e0 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
103f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10400 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
10410 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
10420 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
10430 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10440 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
10450 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
10460 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
10470 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
10480 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
10490 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
104a0 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
104b0 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
104c0 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
104d0 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
104e0 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
104f0 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
10500 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
10510 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10520 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
10530 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
10540 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
10550 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
10560 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
10570 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
10580 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
10590 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
105a0 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
105b0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
105c0 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
105d0 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
105e0 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
105f0 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
10600 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
10610 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
10620 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
10630 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
10640 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
10650 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
10660 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
10670 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
10680 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
10690 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
106a0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
106b0 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
106c0 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
106d0 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
106e0 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
106f0 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
10700 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
10710 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
10720 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
10730 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10740 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
10750 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
10760 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
10770 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
10780 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
10790 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
107a0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
107b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
107c0 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
107d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
107e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
107f0 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
10800 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
10810 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
10820 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
10830 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
10840 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
10850 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
10860 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
10870 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
10880 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
10890 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
108a0 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
108b0 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
108c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
108d0 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
108e0 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
108f0 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
10900 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
10910 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
10920 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
10930 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
10940 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
10950 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
10960 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
10970 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
10980 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
10990 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
109a0 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
109b0 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
109c0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
109d0 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
109e0 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
109f0 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
10a00 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
10a10 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
10a20 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10a30 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
10a40 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
10a50 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
10a60 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
10a70 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
10a80 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
10a90 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
10aa0 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
10ab0 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
10ac0 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
10ad0 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
10ae0 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
10af0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
10b00 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
10b10 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
10b20 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
10b30 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
10b40 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
10b50 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
10b60 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
10b70 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
10b80 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
10b90 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10ba0 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
10bb0 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
10bc0 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
10bd0 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
10be0 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
10bf0 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
10c00 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
10c10 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
10c20 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
10c30 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
10c40 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
10c50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10c60 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
10c70 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
10c80 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10c90 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
10ca0 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
10cb0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10cd0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
10ce0 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
10cf0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
10d00 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
10d10 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
10d20 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
10d30 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
10d40 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
10d50 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
10d60 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
10d70 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
10d80 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
10d90 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
10da0 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
10db0 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
10dc0 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
10dd0 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
10de0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
10df0 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
10e00 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
10e10 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
10e20 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
10e30 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
10e40 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
10e50 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
10e60 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
10e70 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
10e80 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
10e90 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
10ea0 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
10eb0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
10ec0 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
10ed0 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
10ee0 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
10ef0 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
10f00 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
10f10 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
10f20 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63  s given on the c
10f30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
10f40 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
10f50 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
10f60 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
10f70 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
10f80 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
10f90 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
10fa0 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
10fb0 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
10fc0 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
10fd0 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
10fe0 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
10ff0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
11000 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
11010 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
11020 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
11030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11040 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
11050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11060 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
11070 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
11080 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
11090 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
110a0 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
110b0 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
110c0 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
110d0 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
110e0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
110f0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
11100 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
11110 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
11120 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
11130 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
11140 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
11150 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
11160 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
11170 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
11180 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
11190 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
111a0 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
111b0 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
111c0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
111d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
111e0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
111f0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
11200 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
11210 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
11220 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
11230 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
11240 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
11250 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
11260 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
11270 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
11280 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
11290 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
112a0 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
112b0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
112c0 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
112d0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
112e0 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
112f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
11300 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
11310 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
11320 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
11330 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
11340 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
11350 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
11360 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
11370 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
11380 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
11390 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
113a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
113b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
113c0 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
113d0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
113e0 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
113f0 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
11400 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11410 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
11420 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
11430 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11440 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
11450 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
11460 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
11470 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
11480 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
11490 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
114a0 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
114b0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
114c0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
114d0 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
114e0 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
114f0 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
11500 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
11510 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
11520 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
11530 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
11540 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11550 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
11560 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
11570 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
11580 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
11590 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
115a0 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
115b0 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
115c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
115d0 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
115e0 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
115f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11600 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
11610 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
11620 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
11630 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
11640 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
11650 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
11660 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
11670 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
11680 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
11690 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
116a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
116b0 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
116c0 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
116d0 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
116e0 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
116f0 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
11700 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
11710 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
11720 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
11730 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
11740 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
11750 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
11760 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
11770 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
11780 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11790 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
117a0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
117b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
117c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
117d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
117e0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
117f0 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
11800 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
11810 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
11820 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
11830 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
11840 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
11850 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
11860 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
11870 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
11880 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
11890 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
118a0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
118b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
118c0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
118d0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
118e0 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
118f0 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
11900 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
11910 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
11920 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
11930 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
11940 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
11950 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
11960 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11970 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
11980 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
11990 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
119a0 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
119b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
119c0 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
119d0 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
119e0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
119f0 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
11a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
11a10 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
11a20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
11a30 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
11a40 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
11a50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11a60 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
11a70 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
11a80 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
11a90 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
11aa0 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
11ab0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
11ac0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
11ad0 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
11ae0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
11af0 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
11b00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
11b10 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
11b20 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
11b30 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
11b40 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
11b50 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
11b60 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
11b70 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
11b80 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
11b90 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
11ba0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
11bb0 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
11bc0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
11bd0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11be0 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
11bf0 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
11c00 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
11c10 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11c20 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
11c30 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
11c40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11c50 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
11c60 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
11c70 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
11c80 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
11c90 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
11ca0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
11cb0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
11cc0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11cd0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
11ce0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
11cf0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
11d00 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
11d10 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
11d20 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
11d30 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
11d40 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
11d50 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
11d60 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
11d70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
11d80 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
11d90 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
11da0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
11db0 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
11dc0 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
11dd0 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
11de0 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
11df0 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
11e00 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
11e10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
11e20 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
11e30 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
11e40 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
11e50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
11e60 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
11e70 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
11e80 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
11e90 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
11ea0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
11eb0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
11ec0 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
11ed0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
11ee0 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
11ef0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
11f00 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
11f10 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11f20 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
11f30 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
11f40 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
11f50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
11f60 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11f70 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
11f80 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
11f90 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
11fa0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
11fb0 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
11fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
11fd0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
11fe0 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
11ff0 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
12000 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12010 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
12020 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
12030 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
12040 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
12050 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
12060 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
12070 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
12080 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
12090 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
120a0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
120b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
120c0 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
120d0 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
120e0 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
120f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
12100 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
12110 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
12120 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
12130 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
12140 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
12150 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
12160 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
12170 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
12180 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
12190 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
121a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
121b0 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
121c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
121d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
121e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
121f0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
12200 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
12210 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68  DCALL sqlite3_sh
12220 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51  utdown(void);.SQ
12230 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
12240 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
12250 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
12260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
12270 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
12280 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
12290 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
122a0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
122b0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
122c0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
122d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
122e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
122f0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
12300 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
12310 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
12320 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
12330 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
12340 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
12350 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
12360 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
12370 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
12380 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
12390 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
123a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
123b0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
123c0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
123d0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
123e0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
123f0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
12400 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
12410 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
12420 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12430 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
12440 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
12450 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
12460 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
12470 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
12480 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
12490 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
124a0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
124b0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
124c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
124d0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
124e0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
124f0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
12500 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
12510 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
12520 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
12530 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
12540 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
12550 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
12560 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
12570 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
12580 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
12590 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
125a0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
125b0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
125c0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
125d0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
125e0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
125f0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
12600 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
12610 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
12620 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
12630 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
12640 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
12650 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
12660 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12670 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
12680 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
12690 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
126a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
126b0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
126c0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
126d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
126e0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
126f0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
12700 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
12710 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
12720 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12730 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
12740 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
12750 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12760 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
12770 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
12780 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
12790 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
127a0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
127b0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
127c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
127d0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
127e0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
127f0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
12800 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
12810 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
12820 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
12830 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12840 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
12850 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12860 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f  CDECL sqlite3_co
12870 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
12880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12890 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
128a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
128b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
128c0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
128d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
128e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
128f0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
12900 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
12910 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
12920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
12930 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
12940 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
12950 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12960 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
12970 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
12980 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
12990 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
129a0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
129b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
129c0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
129d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
129e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
129f0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
12a00 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
12a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12a20 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
12a30 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
12a40 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
12a50 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
12a60 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
12a70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
12a80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
12a90 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
12aa0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
12ab0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
12ac0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
12ad0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
12ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
12af0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
12b00 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
12b10 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
12b20 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
12b30 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
12b40 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
12b50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12b60 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
12b70 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
12b80 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
12b90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
12ba0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
12bb0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
12bc0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12bd0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12be0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12bf0 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12c00 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12c10 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12c20 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12c30 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12c40 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
12c50 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
12c60 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
12c70 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
12c80 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12c90 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12ca0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
12cb0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
12cc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
12cd0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12ce0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
12cf0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12d00 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
12d10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12d20 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
12d30 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
12d40 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12d50 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
12d60 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
12d70 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
12d80 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
12d90 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
12da0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
12db0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
12dc0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12dd0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12de0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
12df0 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
12e00 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
12e10 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
12e20 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
12e30 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
12e40 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
12e50 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
12e60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12e70 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
12e80 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
12e90 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
12ea0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
12eb0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
12ec0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
12ed0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
12ee0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
12ef0 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
12f00 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
12f10 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
12f20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12f30 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
12f40 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
12f50 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
12f60 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
12f70 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
12f80 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
12f90 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
12fa0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
12fb0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
12fc0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
12fd0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
12fe0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
12ff0 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
13000 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
13010 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
13020 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
13030 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
13040 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
13050 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
13060 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
13070 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
13080 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
13090 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
130a0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
130b0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
130c0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
130d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
130e0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
130f0 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
13100 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
13110 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
13120 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
13130 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
13140 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
13150 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
13160 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
13170 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
13180 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
13190 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
131a0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
131b0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
131c0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
131d0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
131e0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
131f0 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
13200 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
13210 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
13220 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
13230 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
13240 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
13250 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
13260 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
13270 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
13280 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13290 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
132a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
132b0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
132c0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
132d0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
132e0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
132f0 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
13300 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
13310 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
13320 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
13330 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
13340 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
13350 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13360 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
13370 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
13380 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
13390 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
133a0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
133b0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
133c0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
133d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
133e0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
133f0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
13400 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
13410 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
13420 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
13430 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
13440 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
13450 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
13460 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
13470 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
13480 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
13490 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
134a0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
134b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
134c0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
134d0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
134e0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
134f0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
13500 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
13510 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
13520 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
13530 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
13540 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
13550 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
13560 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
13570 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
13580 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
13590 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
135a0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
135b0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
135c0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
135d0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
135e0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
135f0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
13600 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
13610 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
13620 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
13630 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
13640 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
13650 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
13660 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
13670 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
13680 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
13690 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
136a0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
136b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
136c0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
136d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
136e0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
136f0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
13700 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
13710 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
13720 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
13730 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
13740 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
13750 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13760 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
13770 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
13780 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
13790 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
137a0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
137b0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
137c0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
137d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
137e0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
137f0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
13800 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
13810 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
13820 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
13830 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
13840 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
13850 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
13860 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13870 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
13880 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
13890 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
138a0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
138b0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
138c0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
138d0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
138e0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
138f0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
13900 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
13910 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
13920 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
13930 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
13940 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
13950 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
13960 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
13970 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
13980 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
13990 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
139a0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
139b0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
139c0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
139d0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
139e0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
139f0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
13a00 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
13a10 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13a20 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13a30 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
13a40 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
13a50 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
13a60 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
13a70 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
13a80 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
13a90 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
13aa0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
13ab0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
13ac0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
13ad0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
13ae0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
13af0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
13b00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
13b10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
13b20 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
13b30 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
13b40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13b50 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
13b60 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
13b70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13b80 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
13b90 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
13ba0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
13bb0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13bc0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13bd0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13be0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13bf0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13c00 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c10 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13c20 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13c30 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13c40 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13c50 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
13c60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13c70 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
13c80 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
13c90 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
13ca0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13cb0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13cc0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
13cd0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
13ce0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
13cf0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
13d00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13d10 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
13d20 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13d30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13d40 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
13d50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13d60 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
13d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
13d80 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
13d90 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
13da0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
13db0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13dc0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13dd0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
13de0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13df0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13e00 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
13e10 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
13e20 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
13e30 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
13e40 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
13e50 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
13e60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13e70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13e80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13e90 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13ea0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13eb0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13ec0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13ed0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
13ee0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
13ef0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
13f00 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
13f10 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
13f20 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
13f30 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13f40 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
13f50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
13f60 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
13f70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13f80 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
13f90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13fa0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
13fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13fc0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
13fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13fe0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
13ff0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
14000 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
14010 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
14020 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14030 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14040 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
14050 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
14060 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
14070 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
14080 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
14090 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
140a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
140b0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
140c0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
140d0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
140e0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
140f0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
14100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14110 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
14120 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
14130 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
14140 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
14150 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
14160 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
14170 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
14180 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
14190 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
141a0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
141b0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
141c0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
141d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
141e0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
141f0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
14200 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14210 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
14220 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
14230 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
14240 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14250 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
14260 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
14270 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
14280 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
14290 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
142a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
142b0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
142c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
142d0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
142e0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
142f0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
14300 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14310 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
14320 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14330 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
14340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
14350 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
14360 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
14370 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
14380 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
14390 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
143a0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
143b0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
143c0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
143d0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
143e0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
143f0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
14400 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
14410 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
14420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14430 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
14440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
14450 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
14460 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
14470 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
14480 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
14490 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
144a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
144b0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
144c0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
144d0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
144e0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
144f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
14500 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14510 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
14520 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
14530 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
14540 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
14550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14560 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
14570 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
14580 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
14590 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
145a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
145b0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
145c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
145d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
145e0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
145f0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14600 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14610 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14620 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14630 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
14640 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
14650 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
14660 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14670 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
14680 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14690 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
146a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
146b0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
146c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
146d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
146e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
146f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14700 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
14710 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14730 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14740 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14750 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14770 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14780 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14790 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
147a0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
147b0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
147c0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
147d0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
147e0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
147f0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
14800 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
14810 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
14820 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
14830 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
14840 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
14850 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
14860 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
14870 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
14880 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14890 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
148a0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
148b0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
148c0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
148d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
148e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
148f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14900 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
14910 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14930 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14940 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14950 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14960 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14970 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
14980 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
14990 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
149a0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
149b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
149c0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
149d0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
149e0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
149f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14a00 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
14a10 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14a20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14a30 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14a40 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14a50 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
14a60 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
14a70 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
14a80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14a90 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
14aa0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
14ab0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
14ac0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14ae0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
14af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14b00 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
14b10 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14b20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
14b30 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
14b40 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
14b50 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
14b60 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
14b70 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
14b80 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
14b90 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
14ba0 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
14bb0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14bc0 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
14bd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14be0 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
14bf0 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
14c00 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14c10 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
14c20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
14c30 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
14c40 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14c50 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
14c60 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14c70 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14c80 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14c90 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14ca0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14cb0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14cc0 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
14cd0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
14ce0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14cf0 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
14d00 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
14d10 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
14d20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
14d30 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
14d40 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
14d50 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
14d60 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
14d70 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
14d80 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
14d90 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
14da0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14db0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
14dc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14dd0 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
14de0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14df0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14e00 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14e10 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
14e20 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
14e30 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14e40 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  for scratch memo
14e50 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65  ry.  ^(There are
14e60 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
14e70 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  .** to SQLITE_CO
14e80 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41  NFIG_SCRATCH:  A
14e90 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
14ea0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
14eb0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
14ec0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
14ed0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
14ee0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
14ef0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
14f00 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
14f10 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
14f20 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
14f30 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
14f40 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
14f50 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  )^.** The first 
14f60 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
14f70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14f80 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
14f90 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
14fa0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
14fb0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
14fc0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20  SQLite will not 
14fd0 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  use more than on
14fe0 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
14ff0 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a  s per thread..**
15000 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
15010 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
15020 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
15030 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
15040 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
15050 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
15060 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
15070 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
15080 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
15090 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
150a0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
150b0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
150c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
150d0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
150e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
150f0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
15100 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
15110 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e  ded.<p>.** ^When
15120 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15130 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d   provides any am
15140 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20  ount of scratch 
15150 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20  memory using.** 
15160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
15170 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76  RATCH, SQLite av
15180 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79  oids unnecessary
15190 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74   large.** [sqlit
151a0 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61  e3_malloc|heap a
151b0 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20  llocations]..** 
151c0 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52  This can help [R
151d0 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76  obson proof|prev
151e0 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ent memory alloc
151f0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20  ation failures] 
15200 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66  due to heap.** f
15210 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  ragmentation in 
15220 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64  low-memory embed
15230 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20  ded systems..** 
15240 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15260 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
15270 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15280 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
15290 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
152a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
152b0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
152c0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
152d0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
152e0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
152f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
15300 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
15310 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
15320 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
15330 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
15340 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
15350 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
15360 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
15370 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
15380 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
15390 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
153a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
153c0 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  HE2].** configur
153d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ation option..**
153e0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
153f0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
15400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15410 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65  ECACHE: A pointe
15420 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61  r to.** 8-byte a
15430 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
15440 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
15450 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
15460 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
15470 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
15480 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
15490 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
154a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
154b0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
154c0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
154d0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
154e0 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70  512 and 65536) p
154f0 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62  lus some extra b
15500 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ytes for each.**
15510 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
15520 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  The number of ex
15530 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64  tra bytes needed
15540 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61   by the page hea
15550 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  der.** can be de
15560 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74  termined using t
15570 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
15580 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 20  G_PCACHE_HDRSZ] 
15590 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73  option .** to [s
155a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
155b0 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d  ..** ^It is harm
155c0 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
155d0 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
155e0 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ry,.** for the s
155f0 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  z parameter to b
15600 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65  e larger than ne
15610 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 66 69  cessary.  The fi
15620 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
15630 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74  should pointer t
15640 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
15650 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
15660 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  ory that.** is a
15670 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
15680 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74  es of memory, ot
15690 68 65 72 77 69 73 65 20 73 75 62 73 65 71 75 65  herwise subseque
156a0 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  nt behavior is.*
156b0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  * undefined..** 
156c0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
156d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
156e0 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
156f0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
15700 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
15710 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
15720 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
15730 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
15740 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
15750 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
15760 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
15770 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
15780 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
15790 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
157a0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
157b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
157c0 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
157d0 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
157e0 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a  ge space.</dd>.*
157f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15800 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
15810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
15820 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
15830 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15840 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73  IG_HEAP option s
15850 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
15860 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
15870 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
15880 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c  will use for all
15890 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
158a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
158b0 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e  n needs.** beyon
158c0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
158d0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
158e0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
158f0 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  and.** [SQLITE_C
15900 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15910 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
15920 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
15930 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15940 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
15950 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
15960 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
15970 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
15980 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
15990 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
159a0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
159b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
159c0 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
159d0 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
159e0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
159f0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
15a00 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
15a10 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
15a20 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
15a30 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
15a40 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
15a50 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
15a60 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
15a70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
15a80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
15a90 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
15aa0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
15ab0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
15ac0 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
15ad0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
15ae0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15af0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
15b00 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
15b10 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
15b20 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
15b30 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
15b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15b50 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
15b60 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
15b70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
15b80 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
15b90 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
15ba0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
15bb0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
15bc0 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
15bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15be0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
15bf0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15c00 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
15c10 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
15c20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
15c30 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
15c40 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
15c50 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
15c60 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
15c70 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
15c80 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
15c90 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
15ca0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
15cb0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
15cc0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15cd0 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
15ce0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
15cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15d00 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
15d10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15d20 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
15d30 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15d40 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
15d50 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15d60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15d70 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15d80 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
15d90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15da0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15db0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15dc0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
15dd0 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
15de0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
15df0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15e00 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
15e10 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
15e20 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
15e30 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
15e40 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
15e50 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
15e60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15e70 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
15e80 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
15e90 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
15ea0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15eb0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
15ec0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15ed0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15ee0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15ef0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15f00 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15f10 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15f20 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
15f30 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
15f40 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
15f50 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
15f60 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
15f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15f80 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
15f90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15fa0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15fb0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
15fc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
15fd0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
15fe0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15ff0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
16000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16010 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
16020 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
16030 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
16040 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16050 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
16060 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
16070 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
16080 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
16090 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
160a0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
160b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
160c0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
160d0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
160e0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
160f0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
16100 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
16110 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
16120 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
16130 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
16140 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
16150 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
16160 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
16170 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
16180 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
16190 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
161a0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
161b0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
161c0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
161d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
161e0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
161f0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16200 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16210 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16220 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
16230 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
16240 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
16250 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
16260 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
16270 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
16280 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
16290 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
162a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
162b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
162c0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
162d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
162e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
162f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16300 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
16310 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16320 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
16330 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
16340 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
16350 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
16360 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
16370 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
16380 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
16390 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
163a0 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
163b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
163c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
163d0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
163e0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
163f0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16400 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
16410 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
16420 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
16430 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
16440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16450 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
16460 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
16470 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
16480 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
16490 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
164a0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
164b0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
164c0 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
164d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
164e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
164f0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
16500 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
16510 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
16520 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
16530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16550 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
16560 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
16570 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
16580 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16590 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
165a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
165b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
165c0 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
165d0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
165e0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
165f0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
16600 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
16610 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
16620 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
16630 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
16640 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
16650 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
16660 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16670 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
16680 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
16690 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
166a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
166b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
166c0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
166d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
166e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
166f0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
16700 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16710 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16720 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16730 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
16740 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16750 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
16760 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
16770 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
16780 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
16790 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
167a0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
167b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
167c0 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
167d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
167e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16800 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16810 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
16820 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
16830 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
16840 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
16850 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
16860 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
16870 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
16880 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
16890 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
168a0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
168b0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
168c0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
168d0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
168e0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
168f0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
16900 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
16910 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
16920 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
16930 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
16940 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
16950 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
16960 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
16970 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
16980 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
16990 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
169a0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
169b0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
169c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
169d0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
169e0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
169f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
16a00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16a10 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
16a20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
16a30 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
16a40 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
16a50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
16a60 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
16a70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
16a80 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
16a90 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
16aa0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
16ab0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16ac0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
16ad0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
16ae0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
16af0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
16b00 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
16b10 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
16b20 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
16b30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
16b40 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
16b50 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
16b60 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
16b70 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
16b80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
16b90 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
16ba0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
16bb0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
16bc0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
16bd0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
16be0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
16bf0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
16c00 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
16c10 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
16c20 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
16c30 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
16c40 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
16c50 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16c60 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
16c70 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
16c80 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16ca0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
16cb0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
16cc0 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
16cd0 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
16ce0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16cf0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
16d00 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
16d10 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
16d20 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16d30 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
16d40 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
16d50 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
16d60 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
16d70 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
16d80 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
16d90 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16da0 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
16db0 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
16dc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16dd0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
16de0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
16df0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
16e00 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
16e10 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
16e20 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
16e30 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
16e40 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
16e50 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
16e60 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
16e70 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
16e80 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16e90 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
16ea0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16eb0 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
16ec0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
16ed0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
16ee0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
16ef0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
16f00 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
16f10 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
16f20 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
16f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
16f40 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
16f50 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
16f60 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
16f70 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
16f80 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
16f90 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
16fa0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
16fb0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
16fc0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
16fd0 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
16fe0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16ff0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17000 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
17010 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
17020 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
17030 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17040 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
17050 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
17060 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17070 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
17080 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
17090 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
170a0 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
170b0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
170c0 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
170d0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
170e0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
170f0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
17100 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
17110 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
17120 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
17130 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
17140 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
17150 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17160 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
17170 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
17180 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
17190 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
171a0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
171b0 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
171c0 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
171d0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
171e0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
171f0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
17200 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
17210 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
17220 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
17230 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
17240 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
17250 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
17260 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
17270 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
17280 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
17290 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
172a0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
172b0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
172c0 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
172d0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
172e0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
172f0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
17300 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
17310 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17320 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
17330 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
17340 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17350 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
17360 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17370 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
17380 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
17390 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
173a0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
173b0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
173c0 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
173d0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
173e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
173f0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
17400 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
17410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17420 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
17430 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17440 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
17450 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
17460 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
17470 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
17480 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
17490 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
174a0 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
174b0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
174c0 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
174d0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
174e0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
174f0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
17500 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
17510 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
17520 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
17530 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
17540 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
17550 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
17560 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
17570 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
17580 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
17590 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
175a0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
175b0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
175c0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
175d0 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
175e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
175f0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
17600 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17610 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
17620 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17630 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
17640 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
17650 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
17660 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
17670 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
17680 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
17690 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
176a0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
176b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
176c0 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
176d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
176e0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
176f0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
17700 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
17710 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
17720 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
17730 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
17740 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
17750 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
17760 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
17780 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
17790 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
177a0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
177b0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
177c0 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
177d0 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
177e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
177f0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
17800 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
17810 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
17820 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
17830 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
17840 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
17850 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17860 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
17870 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17880 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
17890 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
178a0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
178b0 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
178c0 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
178d0 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
178e0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
178f0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
17900 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
17910 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
17920 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
17930 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
17940 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
17950 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
17960 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
17970 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
17980 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
17990 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
179a0 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
179b0 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
179c0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
179d0 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
179e0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
179f0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
17a00 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
17a10 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
17a20 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
17a30 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
17a40 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
17a50 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
17a60 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
17a70 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
17a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
17a90 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
17aa0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
17ab0 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
17ac0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
17ad0 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
17ae0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
17af0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
17b00 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
17b10 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
17b20 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
17b30 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
17b40 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
17b50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17b60 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
17b70 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17b80 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17b90 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
17ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
17bb0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
17bc0 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
17bd0 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
17be0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
17bf0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
17c00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
17c10 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
17c20 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
17c30 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
17c40 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17c50 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
17c60 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
17c70 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
17c80 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
17c90 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
17ca0 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
17cb0 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
17cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17cd0 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
17ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17cf0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
17d00 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17d10 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17d20 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
17d30 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17d40 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
17d50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17d60 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
17d70 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
17d80 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
17d90 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
17da0 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
17db0 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
17dc0 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
17dd0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
17de0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
17df0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
17e00 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
17e10 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
17e20 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
17e30 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
17e40 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
17e50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
17e60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
17e70 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17e80 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
17e90 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17ea0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
17eb0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
17ec0 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
17ed0 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
17ee0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
17ef0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
17f00 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
17f10 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
17f20 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
17f30 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
17f40 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
17f50 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
17f60 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
17f70 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
17f80 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
17f90 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
17fa0 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
17fb0 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
17fc0 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
17fd0 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
17fe0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
17ff0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
18000 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
18010 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
18020 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
18030 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
18040 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
18050 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
18060 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
18070 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
18080 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
18090 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
180a0 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c  s value..** </dl
180b0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
180c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
180d0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
180e0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
180f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
18100 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
18110 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
18120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
18130 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
18140 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
18150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
18160 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
18170 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
18180 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
181a0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
181b0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
181c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
181d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
181e0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
181f0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
18200 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
18210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18220 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
18230 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
18240 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
18250 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18260 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
18270 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
18280 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
18290 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
182a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
182b0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
182c0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
182d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
182e0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
182f0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
18300 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
18310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18320 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
18330 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
18340 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
18350 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
18360 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
18370 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
18380 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
18390 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
183a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
183b0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
183c0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
183d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
183e0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
183f0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
18400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18410 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
18420 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
18430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18440 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
18450 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
18460 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
18470 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18480 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
18490 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
184a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
184b0 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
184c0 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
184d0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
184e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
184f0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
18500 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
18510 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
18520 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
18530 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
18540 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
18550 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
18560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18570 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
18580 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
18590 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
185a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
185b0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
185c0 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
185d0 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
185e0 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
185f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
18600 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
18610 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
18620 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
18630 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
18640 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32  E_HDRSZ        2
18650 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a  4  /* int *psz *
18660 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18670 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20  _CONFIG_PMASZ   
18680 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
18690 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  /* unsigned int 
186a0 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  szPma */../*.** 
186b0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
186c0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
186d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
186e0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
186f0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
18700 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
18710 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
18720 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
18730 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
18740 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
18750 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
18760 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18770 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
18780 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
18790 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
187a0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
187b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
187c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
187d0 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
187e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
187f0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
18800 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
18810 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
18820 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
18830 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
18840 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
18850 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
18860 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
18870 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
18880 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
18890 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
188a0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
188b0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
188c0 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
188d0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
188e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
188f0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
18900 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
18910 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18920 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
18930 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18940 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
18950 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
18960 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
18970 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
18980 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
18990 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
189a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
189b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
189c0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
189d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
189e0 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
189f0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
18a00 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
18a10 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
18a20 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
18a30 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
18a40 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
18a50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
18a60 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
18a70 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18a80 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
18a90 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
18aa0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
18ab0 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
18ac0 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
18ad0 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
18ae0 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
18af0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
18b00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18b10 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
18b20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
18b30 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
18b40 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
18b50 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
18b60 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
18b70 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
18b80 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
18b90 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
18ba0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
18bb0 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
18bc0 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
18bd0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
18be0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
18bf0 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
18c00 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
18c10 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
18c20 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
18c30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
18c40 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
18c50 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
18c60 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
18c70 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
18c80 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
18c90 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
18ca0 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
18cb0 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
18cc0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
18cd0 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
18ce0 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
18cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
18d00 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
18d10 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
18d20 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
18d30 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
18d40 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18d50 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
18d60 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
18d70 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
18d80 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
18d90 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
18da0 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
18db0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
18dc0 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
18dd0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
18de0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
18df0 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
18e00 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
18e10 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
18e20 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
18e30 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
18e40 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
18e50 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
18e60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
18e70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18e80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18e90 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
18ea0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18eb0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18ec0 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18ed0 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
18ee0 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
18ef0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
18f00 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
18f10 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18f20 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18f30 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
18f40 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
18f50 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
18f60 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
18f70 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
18f80 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
18f90 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
18fa0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
18fb0 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
18fc0 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
18fd0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18fe0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18ff0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
19000 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
19010 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
19020 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
19030 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
19040 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
19050 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
19060 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19070 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
19080 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
19090 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
190a0 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
190b0 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
190c0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
190d0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
190e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
190f0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19100 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
19110 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
19120 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
19130 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
19140 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19150 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
19160 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
19170 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
19180 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
19190 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
191a0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
191b0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
191c0 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
191d0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
191e0 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
191f0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19200 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
19210 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
19220 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19230 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19240 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
19250 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
19260 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
19270 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
19280 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
19290 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
192a0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
192b0 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
192c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
192d0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
192e0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
192f0 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
19300 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
19310 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
19320 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
19330 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
19340 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19350 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
19360 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
19370 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
19380 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19390 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
193a0 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
193b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
193c0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
193d0 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
193e0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
193f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19400 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
19410 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
19420 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
19430 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19440 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19450 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
19460 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
19470 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
19480 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
19490 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
194a0 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
194b0 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
194c0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
194d0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
194e0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
194f0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
19500 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c  tibility..*/.SQL
19510 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
19520 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
19530 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19540 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
19550 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
19560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19570 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
19580 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
19590 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
195a0 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
195b0 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
195c0 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
195d0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
195e0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
195f0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
19600 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
19610 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
19620 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
19630 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
19640 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
19650 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
19660 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
19670 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
19680 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
19690 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
196a0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
196b0 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
196c0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
196d0 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
196e0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
196f0 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
19700 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
19710 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
19720 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
19730 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
19740 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19750 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19760 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
19770 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
19780 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
19790 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
197a0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
197b0 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
197c0 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
197d0 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
197e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
197f0 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
19800 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
19810 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
19820 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
19830 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
19840 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
19850 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
19860 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
19870 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
19880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
19890 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
198a0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
198b0 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
198c0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
198d0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
198e0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
198f0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
19900 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
19910 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
19920 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
19930 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
19940 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
19950 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
19960 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
19970 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
19980 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
19990 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
199a0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
199b0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
199c0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
199d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
199e0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
199f0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
19a00 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
19a10 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
19a20 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
19a30 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
19a40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
19a50 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
19a60 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
19a70 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
19a80 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
19a90 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
19aa0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
19ab0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
19ac0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
19ad0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
19ae0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
19af0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
19b00 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
19b10 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
19b20 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
19b30 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
19b40 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19b50 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
19b60 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
19b70 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
19b80 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
19b90 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
19ba0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
19bb0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
19bc0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
19bd0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19be0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19bf0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19c00 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19c10 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
19c20 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
19c30 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
19c40 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
19c50 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
19c60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19c70 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
19c80 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
19c90 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
19ca0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
19cb0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
19cc0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
19cd0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19ce0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19cf0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19d00 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19d10 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
19d20 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
19d30 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
19d40 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
19d50 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
19d60 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
19d70 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19d80 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19d90 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19da0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19db0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19dc0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19dd0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19de0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19df0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19e00 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19e10 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19e20 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
19e30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19e40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
19e50 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19e60 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
19e70 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
19e80 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19e90 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19ea0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19eb0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
19ec0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
19ed0 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  3_int64 SQLITE_S
19ee0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c  TDCALL sqlite3_l
19ef0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19f00 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19f10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
19f20 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
19f30 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19f40 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19f50 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
19f60 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
19f70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19f80 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
19f90 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
19fa0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
19fb0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
19fc0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
19fd0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
19fe0 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
19ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a000 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
1a010 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1a020 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
1a030 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
1a040 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1a050 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
1a060 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
1a070 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
1a080 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
1a090 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
1a0a0 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
1a0b0 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
1a0c0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1a0d0 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
1a0e0 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
1a0f0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
1a100 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
1a110 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
1a120 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
1a130 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
1a140 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
1a150 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
1a160 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a170 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
1a180 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1a190 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1a1a0 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
1a1b0 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
1a1c0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
1a1d0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a1e0 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
1a1f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1a200 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
1a210 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
1a220 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a230 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
1a240 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
1a250 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
1a260 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
1a270 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
1a280 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
1a290 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
1a2a0 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
1a2b0 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
1a2c0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a2d0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a2e0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
1a2f0 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
1a300 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
1a310 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
1a320 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
1a330 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
1a340 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1a350 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
1a360 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
1a370 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
1a380 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
1a390 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
1a3a0 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
1a3b0 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
1a3c0 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
1a3d0 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
1a3e0 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
1a3f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1a400 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
1a410 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1a420 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
1a430 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
1a440 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
1a450 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
1a460 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
1a470 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
1a480 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
1a490 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
1a4a0 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
1a4b0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
1a4c0 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
1a4d0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
1a4e0 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
1a4f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a500 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1a510 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
1a520 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
1a530 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
1a540 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
1a550 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
1a560 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
1a570 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
1a580 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
1a590 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a5a0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
1a5b0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
1a5c0 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
1a5d0 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
1a5e0 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
1a5f0 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
1a600 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
1a610 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
1a620 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a630 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
1a640 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
1a650 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
1a660 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1a670 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1a680 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
1a690 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
1a6a0 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
1a6b0 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
1a6c0 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
1a6d0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
1a6e0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1a6f0 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
1a700 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
1a710 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a720 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
1a730 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a740 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
1a750 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a760 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
1a770 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
1a780 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a790 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a7a0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1a7b0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
1a7c0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1a7d0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a7e0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a7f0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a800 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a810 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
1a820 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a830 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a840 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1a850 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1a860 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1a870 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1a880 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1a890 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1a8a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1a8b0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1a8c0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1a8d0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1a8e0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1a8f0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1a900 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61  CALL sqlite3_cha
1a910 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1a920 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a930 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
1a940 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
1a950 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1a960 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
1a970 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1a980 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
1a990 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64  of rows inserted
1a9a0 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a  , modified or.**
1a9b0 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20   deleted by all 
1a9c0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1a9d0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1a9e0 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65  tatements comple
1a9f0 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ted.** since the
1aa00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aa10 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c  tion was opened,
1aa20 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65   including those
1aa30 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20   executed as.** 
1aa40 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20  part of trigger 
1aa50 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75  programs. ^Execu
1aa60 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1aa70 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1aa80 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ment.** does not
1aa90 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75   affect the valu
1aaa0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1aab0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1aac0 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43  ges()..** .** ^C
1aad0 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70  hanges made as p
1aae0 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20  art of [foreign 
1aaf0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
1ab00 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
1ab10 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74  .** count, but t
1ab20 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72  hose made as par
1ab30 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  t of REPLACE con
1ab40 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1ab50 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e  on are.** not. ^
1ab60 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1ab70 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1ab80 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41  cepted by INSTEA
1ab90 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a  D OF triggers .*
1aba0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
1abb0 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c  d..** .** See al
1abc0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1abd0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1abe0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1abf0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1ac00 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
1ac10 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
1ac20 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1ac30 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1ac40 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1ac50 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1ac60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ac70 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1ac80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1ac90 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1aca0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1acb0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
1acc0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1acd0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1ace0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
1acf0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1ad00 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74  CALL sqlite3_tot
1ad10 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
1ad20 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ad30 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
1ad40 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
1ad50 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
1ad60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1ad70 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
1ad80 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
1ad90 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1ada0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
1adb0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
1adc0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
1add0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
1ade0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
1adf0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
1ae00 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
1ae10 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
1ae20 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
1ae30 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
1ae40 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
1ae50 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
1ae60 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
1ae70 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
1ae80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
1ae90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1aea0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
1aeb0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
1aec0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
1aed0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
1aee0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
1aef0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
1af00 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
1af10 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
1af20 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1af30 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
1af40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1af50 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
1af60 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
1af70 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
1af80 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
1af90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
1afa0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
1afb0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
1afc0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
1afd0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
1afe0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1aff0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
1b000 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
1b010 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
1b020 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
1b030 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
1b040 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
1b050 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
1b060 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
1b070 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
1b080 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
1b090 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
1b0a0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
1b0b0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
1b0c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1b0d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1b0e0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
1b0f0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
1b100 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1b110 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
1b120 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
1b130 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
1b140 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
1b150 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
1b160 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b170 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
1b180 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
1b190 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
1b1a0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1b1b0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
1b1c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b1d0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
1b1e0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
1b1f0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1b200 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1b210 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b220 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
1b230 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
1b240 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1b250 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
1b260 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
1b270 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
1b280 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
1b290 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
1b2a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1b2b0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
1b2c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1b2d0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1b2e0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
1b2f0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
1b300 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1b310 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
1b320 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
1b330 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
1b340 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
1b350 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1b360 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
1b370 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
1b380 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1b390 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
1b3a0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
1b3b0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
1b3c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1b3d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1b3e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1b3f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
1b400 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
1b410 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b420 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
1b430 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
1b440 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
1b450 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
1b460 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
1b470 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
1b480 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1b490 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1b4a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b4b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b4c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1b4d0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1b4e0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1b4f0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1b500 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1b510 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1b520 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1b530 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1b540 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1b550 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1b560 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1b570 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1b580 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1b590 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1b5a0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1b5b0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1b5c0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1b5d0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1b5e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1b5f0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1b600 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1b610 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1b620 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1b630 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1b640 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1b650 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1b660 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1b670 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1b680 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1b690 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1b6a0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1b6b0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1b6c0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1b6d0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1b6e0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1b6f0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1b700 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1b710 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1b720 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1b730 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1b740 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1b750 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1b760 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1b770 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1b780 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1b790 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1b7a0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1b7b0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1b7c0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1b7d0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1b7e0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1b7f0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1b800 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1b810 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1b820 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1b830 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1b840 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1b850 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1b860 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1b870 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1b880 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1b890 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1b8a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b8b0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1b8c0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1b8d0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1b8e0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1b8f0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1b900 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1b910 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1b920 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1b930 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1b940 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1b950 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1b960 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1b970 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1b980 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1b990 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b9a0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1b9b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1b9c0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1b9d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1b9e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1b9f0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1ba00 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1ba10 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1ba20 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1ba30 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1ba40 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1ba50 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1ba60 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1ba70 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1ba80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1ba90 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1baa0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1bab0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1bac0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1bad0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1bae0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1baf0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1bb00 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
1bb10 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1bb20 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
1bb30 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1bb40 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
1bb50 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1bb60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
1bb70 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1bb80 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1bb90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1bba0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1bbb0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1bbc0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1bbd0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1bbe0 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1bbf0 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1bc00 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1bc10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1bc20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1bc30 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1bc40 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1bc50 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1bc60 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1bc70 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1bc80 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1bc90 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1bca0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1bcb0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1bcc0 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1bcd0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1bce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1bcf0 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1bd00 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1bd10 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1bd20 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1bd30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bd40 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1bd50 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1bd60 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1bd70 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1bd80 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1bd90 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1bda0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1bdb0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1bdc0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1bdd0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1bde0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1bdf0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1be00 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1be10 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1be20 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1be30 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1be40 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1be50 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1be60 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1be70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1be80 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1be90 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1bea0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1beb0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1bec0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1bed0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1bee0 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1bef0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1bf00 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1bf10 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1bf20 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1bf30 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1bf40 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1bf50 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1bf60 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1bf70 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1bf80 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1bf90 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1bfa0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1bfb0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1bfc0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1bfd0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1bfe0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1bff0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1c000 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1c010 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1c020 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1c030 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1c040 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1c050 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1c060 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1c070 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1c080 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1c090 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1c0a0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1c0b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1c0c0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1c0d0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1c0e0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1c0f0 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1c100 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1c110 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1c120 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1c130 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1c140 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1c150 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1c160 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1c170 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1c180 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1c190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1c1a0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1c1b0 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1c1c0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1c1d0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1c1e0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1c1f0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1c200 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1c210 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1c220 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1c230 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1c240 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1c250 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1c260 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1c270 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1c280 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1c290 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1c2a0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1c2b0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1c2c0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1c2d0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1c2e0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1c2f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1c300 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1c310 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1c320 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1c330 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1c340 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1c350 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1c360 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1c370 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1c380 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1c390 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1c3a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1c3b0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1c3c0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1c3d0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1c3e0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1c3f0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1c400 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1c410 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1c420 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1c430 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1c440 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1c450 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1c460 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1c470 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1c480 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1c490 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1c4a0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1c4b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c4c0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1c4d0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1c4e0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1c4f0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1c500 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1c510 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1c520 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1c530 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1c540 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1c550 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1c560 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1c570 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1c580 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1c590 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1c5a0 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1c5b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1c5c0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1c5d0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1c5e0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1c5f0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1c600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c610 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c620 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1c630 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1c640 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1c650 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1c660 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1c670 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1c680 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1c690 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1c6a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1c6b0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1c6c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c6d0 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1c6e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1c6f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c700 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1c710 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1c720 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1c730 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c740 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1c750 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1c760 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1c770 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1c780 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1c790 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c7a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c7b0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1c7c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c7d0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1c7e0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1c7f0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1c800 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1c810 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1c820 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1c830 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1c840 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1c850 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1c860 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c870 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1c880 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1c890 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1c8a0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c8b0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c8c0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1c8d0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1c8e0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1c8f0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1c900 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1c910 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1c920 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1c930 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1c940 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1c950 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1c960 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1c970 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1c980 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1c990 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1c9a0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1c9b0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1c9c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c9d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1c9e0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1c9f0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1ca00 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1ca10 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1ca20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ca30 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1ca40 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1ca50 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1ca60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1ca70 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1ca80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1ca90 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1caa0 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54  imeout].*/.SQLIT
1cab0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
1cac0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1cad0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1cae0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1caf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cb00 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1cb10 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1cb20 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1cb30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1cb40 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1cb50 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1cb60 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1cb70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1cb80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1cb90 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1cba0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1cbb0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1cbc0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1cbd0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1cbe0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1cbf0 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1cc00 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1cc10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1cc20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1cc30 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1cc40 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1cc50 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1cc60 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1cc70 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1cc80 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1cc90 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1cca0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1ccb0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1ccc0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1ccd0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1cce0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1ccf0 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1cd00 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1cd10 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1cd20 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1cd30 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1cd40 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1cd50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1cd60 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1cd70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1cd80 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1cd90 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1cda0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1cdb0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1cdc0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1cdd0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1cde0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1cdf0 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1ce00 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1ce10 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1ce20 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1ce30 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1ce40 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1ce50 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1ce60 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1ce70 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1ce80 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1ce90 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1cea0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1ceb0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1cec0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1ced0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1cee0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1cef0 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1cf00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1cf10 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1cf20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1cf30 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1cf40 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1cf50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1cf60 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1cf70 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1cf80 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1cf90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1cfa0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1cfb0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1cfc0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1cfd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1cfe0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1cff0 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1d000 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1d010 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1d020 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1d030 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1d040 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1d050 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d060 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1d070 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1d080 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1d090 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1d0a0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1d0b0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1d0c0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1d0d0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1d0e0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1d0f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d100 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1d110 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1d120 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1d130 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1d140 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1d150 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1d160 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1d170 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1d180 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1d190 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1d1a0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1d1b0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1d1c0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1d1d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d1e0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1d1f0 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1d200 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1d210 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d220 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1d230 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d240 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1d250 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d260 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1d270 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d280 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1d290 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1d2a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1d2b0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1d2c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1d2d0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1d2e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d2f0 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1d300 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d310 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1d320 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1d330 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1d340 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1d350 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1d360 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1d370 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1d380 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1d390 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1d3a0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1d3b0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1d3c0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1d3d0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1d3e0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1d3f0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1d400 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1d410 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1d420 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1d430 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1d440 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d450 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1d460 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1d470 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1d480 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d490 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1d4a0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1d4b0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1d4c0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1d4d0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1d4e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1d4f0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1d500 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1d510 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1d520 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1d530 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1d540 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1d550 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1d560 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1d570 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d580 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1d590 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1d5a0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1d5b0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1d5c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d5d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1d5e0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1d5f0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1d600 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1d610 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1d620 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1d630 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1d640 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1d650 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1d660 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1d670 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1d680 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1d690 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1d6a0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1d6b0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1d6c0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1d6d0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1d6e0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1d6f0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1d700 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1d710 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1d720 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1d730 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1d740 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1d750 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1d760 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1d770 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1d780 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1d790 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74  CALL sqlite3_get
1d7a0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1d7b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d7c0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1d7d0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1d7e0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1d7f0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1d800 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1d810 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1d820 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1d830 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1d840 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1d850 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1d860 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1d870 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1d880 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1d890 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d8a0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1d8b0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d8c0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1d8d0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1d8e0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1d8f0 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  re */.);.SQLITE_
1d900 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
1d910 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1d920 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1d930 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1d940 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1d950 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1d960 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1d970 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d980 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1d990 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1d9a0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1d9b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1d9c0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1d9d0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
1d9e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64  ese routines und
1d9f0 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20  erstand most of 
1da00 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66  the common K&R f
1da10 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1da20 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  s,.** plus some 
1da30 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1da40 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c  tandard formats,
1da50 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e   detailed below.
1da60 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f  .** Note that so
1da70 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f  me of the more o
1da80 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e  bscure formattin
1da90 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72  g options from r
1daa0 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61  ecent.** C-libra
1dab0 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65  ry standards are
1dac0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1dad0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  is implementatio
1dae0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
1daf0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1db00 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1db10 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1db20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1db30 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1db40 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1db50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1db60 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1db70 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1db80 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1db90 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1dba0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1dbb0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1dbc0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1dbd0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1dbe0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1dbf0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1dc00 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1dc10 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1dc20 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1dc30 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1dc40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1dc50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1dc60 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1dc70 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1dc80 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1dc90 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1dca0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1dcb0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1dcc0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1dcd0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1dce0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1dcf0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1dd00 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1dd10 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1dd20 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1dd30 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1dd40 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1dd50 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1dd60 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1dd70 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1dd80 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1dd90 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1dda0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1ddb0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1ddc0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1ddd0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1dde0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1ddf0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1de00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1de10 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1de20 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1de30 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1de40 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1de50 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1de60 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1de70 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1de80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1de90 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1dea0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1deb0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1dec0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1ded0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1dee0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1def0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1df00 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1df10 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1df20 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1df30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1df40 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1df50 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1df60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1df70 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1df80 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1df90 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1dfa0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1dfb0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1dfc0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1dfd0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1dfe0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1dff0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1e000 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1e010 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1e020 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1e030 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1e040 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1e050 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1e060 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1e070 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1e080 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1e090 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1e0a0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1e0b0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1e0c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1e0d0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1e0e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1e0f0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1e100 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1e110 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1e120 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1e130 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1e140 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1e150 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e160 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1e170 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1e180 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1e190 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a  Q", "%w" and "%z
1e1a0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1e1b0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1e1c0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1e1d0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1e1e0 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1e1f0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1e200 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1e210 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1e220 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1e230 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1e240 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1e250 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1e260 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1e270 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1e280 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1e290 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1e2a0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1e2b0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1e2c0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1e2d0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1e2e0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1e2f0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1e300 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1e310 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1e320 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1e330 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e340 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e350 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1e360 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1e370 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1e380 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e390 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1e3a0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1e3b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1e3c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e3d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e3e0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1e3f0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1e400 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1e410 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1e420 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e430 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e440 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e450 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e460 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e470 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e480 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1e490 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1e4a0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1e4b0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1e4c0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1e4d0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1e4e0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1e4f0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1e500 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e510 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1e520 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1e530 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1e540 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1e550 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e560 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1e570 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1e580 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1e590 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1e5a0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1e5b0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1e5c0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1e5d0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1e5e0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1e5f0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1e600 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1e610 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e620 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1e630 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1e640 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1e650 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1e660 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1e670 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1e680 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1e690 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1e6a0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1e6b0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1e6c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1e6d0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e6e0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1e6f0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1e700 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1e710 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1e720 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1e730 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1e740 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1e750 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1e760 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1e770 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1e780 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1e790 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1e7a0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1e7b0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1e7c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1e7d0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1e7e0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e7f0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1e800 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1e810 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1e820 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1e830 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1e840 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1e850 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1e860 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1e870 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1e880 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1e8a0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1e8b0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1e8c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1e8d0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1e8e0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1e8f0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1e900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e910 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22  **.** ^(The "%w"
1e920 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e930 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20  on is like "%q" 
1e940 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65  except that it e
1e950 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20  xpects to.** be 
1e960 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1e970 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69   double-quotes i
1e980 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65  nstead of single
1e990 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a   quotes, and it.
1e9a0 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64  ** escapes the d
1e9b0 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72  ouble-quote char
1e9c0 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  acter instead of
1e9d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74   the single-quot
1e9e0 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29  e.** character.)
1e9f0 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d  ^  The "%w" form
1ea00 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1ea10 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61   intended for sa
1ea20 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a  fely inserting.*
1ea30 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  * table and colu
1ea40 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20  mn names into a 
1ea50 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20  constructed SQL 
1ea60 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1ea70 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1ea80 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1ea90 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1eaa0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1eab0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1eac0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1ead0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1eae0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1eaf0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1eb00 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1eb10 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1eb20 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1eb30 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1eb40 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c  SQLITE_CDECL sql
1eb50 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1eb60 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53  st char*,...);.S
1eb70 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1eb80 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1eb90 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1eba0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1ebb0 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  list);.SQLITE_AP
1ebc0 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43  I char *SQLITE_C
1ebd0 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70  DECL sqlite3_snp
1ebe0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1ebf0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1ec00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1ec10 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
1ec20 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  LL sqlite3_vsnpr
1ec30 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1ec40 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1ec50 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1ec60 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1ec70 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1ec80 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1ec90 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1eca0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1ecb0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1ecc0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1ecd0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1ece0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1ecf0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1ed00 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1ed10 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1ed20 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1ed30 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1ed40 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1ed50 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1ed60 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1ed70 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1ed80 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1ed90 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1eda0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1edb0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1edc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1edd0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1ede0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1edf0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1ee00 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1ee10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1ee20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ee30 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1ee40 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1ee50 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1ee60 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1ee70 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1ee80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1ee90 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1eea0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1eeb0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1eec0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1eed0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1eee0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1eef0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ef00 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1ef10 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1ef20 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1ef30 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1ef40 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1ef50 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1ef60 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1ef70 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1ef80 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1ef90 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1efa0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1efb0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1efc0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1efd0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1efe0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1eff0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1f000 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1f010 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1f020 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1f030 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1f040 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1f050 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1f060 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1f070 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1f080 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1f090 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1f0a0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1f0b0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1f0c0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1f0d0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1f0e0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1f0f0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1f100 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1f110 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1f120 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1f130 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1f140 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1f150 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1f160 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1f170 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1f180 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1f190 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1f1a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1f1b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1f1c0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1f1d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1f1e0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1f1f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f200 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f210 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1f220 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1f230 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f240 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1f250 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1f260 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1f270 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f280 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1f290 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1f2a0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1f2b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1f2c0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1f2d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1f2e0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1f2f0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1f300 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1f310 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1f320 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1f330 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f340 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1f350 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1f360 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1f370 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1f380 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1f390 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1f3a0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1f3b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f3c0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1f3d0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1f3e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1f3f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1f400 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1f410 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1f420 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1f430 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1f440 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1f450 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f460 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1f470 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1f480 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f490 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1f4a0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1f4b0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1f4c0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f4d0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f4e0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1f4f0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1f500 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1f510 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1f520 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1f530 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1f540 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1f550 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1f560 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1f570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1f580 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1f590 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1f5a0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1f5b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f5c0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f5d0 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1f5e0 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1f5f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1f600 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1f610 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1f620 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1f630 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1f640 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f650 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f660 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f670 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1f680 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1f690 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f6a0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1f6b0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1f6c0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1f6d0 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1f6e0 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1f6f0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1f700 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f710 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1f720 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1f730 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1f740 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1f750 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1f760 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1f770 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f780 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f790 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f7a0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1f7b0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1f7c0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1f7d0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1f7e0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1f7f0 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1f800 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1f810 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1f820 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1f830 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1f840 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1f850 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1f860 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1f870 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1f880 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1f890 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1f8a0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1f8b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f8c0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1f8d0 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1f8e0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1f8f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f900 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1f910 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1f920 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1f930 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1f940 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1f950 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1f960 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1f970 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1f980 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1f990 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1f9a0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1f9b0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1f9c0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1f9d0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1f9e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1f9f0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1fa00 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1fa10 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1fa20 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1fa30 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1fa40 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1fa50 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1fa60 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1fa70 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1fa80 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1fa90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1faa0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1fab0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1fac0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1fad0 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1fae0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1faf0 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1fb00 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1fb10 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1fb20 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1fb30 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1fb40 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1fb50 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1fb60 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1fb70 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1fb80 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1fb90 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1fba0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1fbb0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1fbc0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1fbd0 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1fbe0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1fbf0 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1fc00 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1fc10 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1fc20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1fc30 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1fc40 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1fc50 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1fc60 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1fc70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1fc80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1fc90 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1fca0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1fcb0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1fcc0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1fcd0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1fce0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1fcf0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1fd00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1fd10 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1fd20 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1fd30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1fd40 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1fd50 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1fd60 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1fd70 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1fd80 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1fd90 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1fda0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1fdb0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1fdc0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1fdd0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1fde0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1fdf0 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  L sqlite3_malloc
1fe00 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
1fe10 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
1fe20 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
1fe30 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1fe40 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  uint64);.SQLITE_
1fe50 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
1fe60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1fe70 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1fe80 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
1fe90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
1fea0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
1feb0 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1fec0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1fed0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1fee0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1fef0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1ff00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
1ff10 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53 51  qlite3_uint64 SQ
1ff20 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1ff30 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a  ite3_msize(void*
1ff40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ff50 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1ff60 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1ff70 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1ff80 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1ff90 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1ffa0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1ffb0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1ffc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ffd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1ffe0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1fff0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
20000 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
20010 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
20020 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
20030 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
20040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
20050 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20060 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
20070 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
20080 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
20090 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
200a0 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
200b0 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
200c0 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
200d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
200e0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
200f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
20100 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
20110 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
20120 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
20130 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
20140 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
20150 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
20160 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
20170 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20180 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
20190 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
201a0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
201b0 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
201c0 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
201d0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
201e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
201f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
20200 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
20210 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
20220 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
20230 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
20240 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
20250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
20260 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
20270 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
20280 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
20290 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
202a0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
202b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
202c0 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
202d0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
202e0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
202f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
20300 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
20310 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
20320 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
20330 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20340 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
20350 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
20360 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
20370 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53   the reset..*/.S
20380 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
20390 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  3_int64 SQLITE_S
203a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
203b0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
203c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
203d0 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
203e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
203f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20400 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
20410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20420 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
20430 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
20440 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
20450 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
20460 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
20470 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
20480 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
20490 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
204a0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
204b0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
204c0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
204d0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
204e0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
204f0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
20500 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
20510 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
20520 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
20530 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
20540 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
20550 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
20560 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
20570 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
20580 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
20590 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
205a0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
205b0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
205c0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
205d0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
205e0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
205f0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
20600 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
20610 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
20620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
20630 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
20640 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
20650 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
20660 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
20670 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
20680 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
20690 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
206a0 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
206b0 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
206c0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
206d0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
206e0 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
206f0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
20700 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
20710 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
20720 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
20730 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
20740 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
20750 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
20760 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
20770 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
20780 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
20790 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
207a0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
207b0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
207c0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
207d0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
207e0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
207f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
20800 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
20810 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  L sqlite3_random
20820 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
20830 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
20840 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
20850 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
20860 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
20870 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
20880 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
20890 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
208a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
208b0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
208c0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
208d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
208e0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
208f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
20900 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
20910 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
20920 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
20930 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
20940 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
20950 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
20960 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
20970 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
20980 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
20990 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
209a0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
209b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
209c0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
209d0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
209e0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
209f0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
20a00 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
20a10 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
20a20 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
20a30 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
20a40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20a50 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
20a60 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
20a70 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
20a80 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20a90 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
20aa0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
20ab0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
20ac0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
20ad0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
20ae0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
20af0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
20b00 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
20b10 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
20b20 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
20b30 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
20b40 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
20b50 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
20b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20b70 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
20b80 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
20b90 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
20ba0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
20bb0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
20bc0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
20bd0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
20be0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
20bf0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
20c00 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
20c10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20c20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20c30 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
20c40 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
20c50 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20c60 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
20c70 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
20c80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20c90 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
20ca0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
20cb0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
20cc0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
20cd0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
20ce0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
20cf0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
20d00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20d10 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20d20 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20d30 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
20d40 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20d50 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20d60 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
20d70 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
20d80 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
20d90 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
20da0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20db0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20dc0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
20dd0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
20de0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20df0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
20e00 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
20e10 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
20e20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
20e30 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
20e40 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
20e50 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
20e60 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
20e70 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
20e80 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
20e90 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
20ea0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
20eb0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
20ec0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
20ed0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
20ee0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
20ef0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
20f00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
20f10 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
20f20 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
20f30 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
20f40 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
20f50 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
20f60 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
20f70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20f80 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
20f90 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
20fa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20fb0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
20fc0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
20fd0 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
20fe0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
20ff0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
21000 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
21010 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
21020 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
21030 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
21040 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
21050 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
21060 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
21070 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
21080 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
21090 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
210a0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
210b0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
210c0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
210d0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
210e0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
210f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
21100 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
21110 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
21120 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
21130 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
21140 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
21150 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
21160 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
21170 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
21180 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
21190 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
211a0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
211b0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
211c0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
211d0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
211e0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
211f0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
21200 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
21210 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
21220 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
21230 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
21240 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
21250 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
21260 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
21270 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
21280 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
21290 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
212a0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
212b0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
212c0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
212d0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
212e0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
212f0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
21300 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
21310 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
21320 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
21330 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
21340 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
21350 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
21360 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
21370 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
21380 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
21390 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
213a0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
213b0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
213c0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
213d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
213e0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
213f0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
21400 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
21410 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
21420 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
21430 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
21440 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
21450 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
21460 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
21470 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
21480 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
21490 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
214a0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
214b0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
214c0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
214d0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
214e0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
214f0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
21500 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
21510 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
21520 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
21530 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
21540 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
21550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21560 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
21570 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
21580 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21590 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
215a0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
215b0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
215c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
215d0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
215e0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
215f0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
21600 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
21610 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
21620 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21630 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
21640 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
21650 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
21660 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21670 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21680 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
21690 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
216a0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
216b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
216c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
216d0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
216e0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
216f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
21700 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
21710 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
21720 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
21730 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
21740 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21750 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
21760 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
21770 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
21780 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
21790 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
217a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
217b0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
217c0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
217d0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
217e0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
217f0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
21800 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
21810 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
21820 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
21830 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
21840 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
21850 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
21860 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21870 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
21880 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
21890 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
218a0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
218b0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
218c0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
218d0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
218e0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
218f0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
21900 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
21910 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
21920 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
21930 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
21940 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
21950 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21960 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
21970 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
21980 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
21990 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
219a0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
219b0 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  LL sqlite3_set_a
219c0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
219d0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
219e0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
219f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21a00 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
21a10 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
21a20 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
21a30 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
21a40 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
21a50 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
21a60 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
21a70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21a80 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
21a90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21aa0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
21ab0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
21ac0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
21ad0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
21ae0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
21af0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
21b00 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
21b10 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
21b20 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
21b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
21b40 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
21b50 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
21b60 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
21b70 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
21b80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
21b90 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
21ba0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
21bb0 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
21bc0 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
21bd0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
21be0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
21bf0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
21c00 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
21c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21c20 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
21c30 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
21c40 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
21c50 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
21c60 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
21c70 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
21c80 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
21c90 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
21ca0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
21cb0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
21cc0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
21cd0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
21ce0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21cf0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
21d00 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
21d10 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
21d20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
21d30 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
21d40 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
21d50 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
21d60 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
21d70 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
21d80 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
21d90 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
21da0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
21db0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
21dc0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
21dd0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
21de0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
21df0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
21e00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
21e10 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
21e20 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
21e30 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
21e40 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
21e50 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
21e60 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
21e70 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
21e80 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
21e90 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
21ea0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
21eb0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
21ec0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
21ed0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
21ee0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
21ef0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
21f00 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
21f10 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
21f20 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
21f30 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
21f40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
21f50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21f60 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
21f70 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
21f80 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
21f90 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
21fa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21fb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21fc0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
21fd0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
21fe0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
21ff0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
22000 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
22010 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
22020 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
22030 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
22040 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
22050 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
22060 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
22070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22080 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22090 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
220a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
220b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
220c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
220d0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
220e0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
220f0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22100 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22110 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22120 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
22130 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
22140 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22150 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22160 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22170 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
22180 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22190 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
221a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
221b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
221c0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
221d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
221e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
221f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22200 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22210 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
22220 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22230 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22240 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22250 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22260 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
22270 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22280 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22290 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
222a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
222b0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
222c0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
222d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
222e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
222f0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
22300 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
22310 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22320 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22340 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
22350 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
22360 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22370 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22390 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
223a0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
223b0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
223c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
223d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
223e0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
223f0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
22400 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22410 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22430 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
22440 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
22450 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22460 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22480 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
22490 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
224a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
224b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
224c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
224d0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
224e0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
224f0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22500 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22520 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
22530 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
22540 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22550 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22560 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22570 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
22580 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
22590 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
225a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
225b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
225c0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
225d0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
225e0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
225f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22600 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
22610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22620 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22630 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22640 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22650 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
22660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
22670 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
22680 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
22690 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
226a0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
226b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
226c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
226d0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
226e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
226f0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
22700 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
22710 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22720 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22730 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22740 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
22750 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
22760 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22770 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22780 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22790 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
227a0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
227b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
227c0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
227d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
227e0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
227f0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
22800 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
22810 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22820 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22830 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
22840 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
22850 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
22860 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22880 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
22890 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
228a0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
228b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
228c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
228d0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
228e0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
228f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
22900 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22920 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
22930 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
22940 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22950 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22970 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
22980 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
22990 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
229a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
229b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
229c0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
229d0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
229e0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
229f0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22a00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
22a10 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
22a20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
22a30 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
22a40 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
22a50 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
22a60 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
22a70 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
22a80 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
22a90 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
22aa0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
22ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22ac0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
22ad0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
22ae0 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
22af0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
22b00 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
22b10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22b20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
22b30 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
22b40 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
22b50 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
22b60 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
22b70 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22b80 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
22b90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
22ba0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
22bb0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
22bc0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
22bd0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
22be0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
22bf0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
22c00 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
22c10 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
22c20 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
22c30 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
22c40 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
22c50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
22c60 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
22c70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
22c80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
22c90 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
22ca0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
22cb0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
22cc0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
22cd0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
22ce0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
22cf0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
22d00 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
22d10 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
22d20 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
22d30 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
22d40 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
22d50 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
22d60 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
22d70 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
22d80 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
22d90 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
22da0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
22db0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
22dc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
22dd0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
22de0 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
22df0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
22e00 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
22e10 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
22e20 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
22e30 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
22e40 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
22e50 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
22e60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
22e70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
22e80 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
22e90 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
22ea0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
22eb0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
22ec0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
22ed0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
22ee0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
22ef0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
22f00 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
22f10 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
22f20 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
22f30 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
22f40 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
22f50 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
22f60 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
22f70 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
22f80 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
22f90 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
22fa0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
22fb0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
22fc0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
22fd0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
22fe0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
22ff0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
23000 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
23010 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
23020 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
23030 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23040 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
23050 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
23060 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
23070 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
23080 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
23090 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
230a0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
230b0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
230c0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
230d0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
230e0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
230f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
23100 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
23110 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
23120 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
23130 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
23140 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
23150 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
23160 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
23170 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
23180 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
23190 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
231a0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
231b0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
231c0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
231d0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
231e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
231f0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
23200 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
23210 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
23220 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
23230 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
23240 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
23250 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
23260 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
23270 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
23280 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
23290 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
232a0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
232b0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
232c0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
232d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
232e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
232f0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
23300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23310 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
23320 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
23330 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
23340 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
23350 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
23360 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
23370 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
23380 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
23390 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
233a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
233b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
233c0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
233d0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
233e0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
233f0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
23400 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
23410 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
23420 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
23430 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
23440 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
23450 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
23460 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
23470 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
23480 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
23490 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
234a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
234b0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
234c0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
234d0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
234e0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
234f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23500 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
23510 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
23520 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
23530 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
23540 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
23550 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
23560 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
23570 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
23580 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23590 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
235a0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
235b0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
235c0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
235d0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
235e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
235f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
23600 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
23610 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
23620 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
23630 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
23640 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
23650 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
23660 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
23670 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
23680 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23690 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
236a0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
236b0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
236c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
236d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
236e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
236f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
23700 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
23710 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23720 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23730 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
23740 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
23750 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23760 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
23770 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
23780 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
23790 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
237a0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
237b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72  DCALL sqlite3_pr
237c0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
237d0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
237e0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
237f0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
23800 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
23810 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
23820 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54  nection.** CONST
23830 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
23840 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
23850 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
23860 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
23870 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
23880 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
23890 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
238a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
238b0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
238c0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
238d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
238e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
238f0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
23900 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
23910 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
23920 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
23930 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
23940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23950 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
23960 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
23970 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
23980 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
23990 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
239a0 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
239b0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
239c0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
239d0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
239e0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
239f0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
23a00 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
23a10 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
23a20 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
23a30 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
23a40 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
23a50 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
23a60 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
23a70 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
23a80 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
23a90 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
23aa0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
23ab0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
23ac0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
23ad0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
23ae0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
23af0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
23b00 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
23b10 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
23b20 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
23b30 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
23b40 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
23b50 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
23b60 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
23b70 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
23b80 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
23b90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
23ba0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
23bb0 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
23bc0 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
23bd0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
23be0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
23bf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23c00 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
23c10 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
23c20 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
23c30 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
23c40 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
23c50 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
23c60 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23c70 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
23c80 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
23c90 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
23ca0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
23cb0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
23cc0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
23cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23ce0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
23cf0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
23d00 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
23d10 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
23d20 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
23d30 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
23d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23d50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
23d60 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
23d70 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
23d80 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
23d90 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
23da0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
23db0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
23dc0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
23dd0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
23de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23df0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
23e00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
23e10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23e20 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
23e30 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
23e40 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
23e50 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
23e60 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
23e70 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
23e80 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
23e90 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
23ea0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
23eb0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
23ec0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23ed0 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
23ee0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
23ef0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
23f00 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
23f10 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
23f20 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
23f30 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
23f40 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
23f50 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
23f60 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
23f70 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
23f80 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
23f90 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
23fa0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
23fb0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23fc0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
23fd0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
23fe0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
23ff0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
24000 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
24010 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
24020 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
24030 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
24040 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
24050 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
24060 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
24070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
24080 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
24090 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
240a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
240b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
240c0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
240d0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
240e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
240f0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
24100 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
24110 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
24120 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
24130 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
24140 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
24150 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
24160 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
24170 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
24180 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
24190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
241a0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
241b0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
241c0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
241d0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
241e0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
241f0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
24200 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
24210 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
24220 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
24230 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
24240 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
24250 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
24260 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
24270 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
24280 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
24290 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
242a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
242b0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
242c0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
242d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
242e0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
242f0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
24300 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
24310 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
24320 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
24330 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
24340 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
24350 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
24360 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
24370 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
24380 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
24390 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
243a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
243b0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
243c0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
243d0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
243e0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
243f0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
24400 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
24410 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
24420 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
24430 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
24440 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
24450 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
24460 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24470 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
24480 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
24490 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
244a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
244b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
244c0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
244d0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
244e0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
244f0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
24500 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
24510 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24520 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
24530 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24540 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
24550 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
24560 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24570 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
24580 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
24590 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
245a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
245b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
245c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
245d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
245e0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
245f0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
24600 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
24610 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
24620 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
24630 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
24640 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
24650 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
24660 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
24670 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
24680 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
24690 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
246a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
246b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
246c0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
246d0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
246e0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
246f0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
24700 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
24710 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
24720 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
24730 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
24740 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
24750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
24760 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
24770 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
24780 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
24790 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
247a0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
247b0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
247c0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
247d0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
247e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
247f0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
24800 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
24810 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
24820 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
24830 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
24840 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
24850 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
24860 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
24870 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
24880 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
24890 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
248a0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
248b0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
248c0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
248d0 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
248e0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
248f0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
24900 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
24910 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
24920 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
24930 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
24940 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24950 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
24960 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
24970 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
24980 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
24990 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
249a0 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
249b0 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
249c0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
249d0 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
249e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
249f0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
24a00 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
24a10 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
24a20 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
24a30 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
24a40 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
24a50 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
24a60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
24a70 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
24a80 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
24a90 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
24aa0 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
24ab0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
24ac0 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
24ad0 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
24ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
24af0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
24b00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
24b10 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
24b20 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
24b30 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
24b40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
24b50 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
24b60 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
24b70 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
24b80 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
24b90 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
24ba0 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
24bb0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
24bc0 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
24bd0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
24be0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
24bf0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
24c00 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
24c10 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
24c20 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
24c30 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
24c40 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
24c50 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
24c60 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
24c70 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
24c80 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
24c90 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
24ca0 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
24cb0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
24cc0 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
24cd0 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
24ce0 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
24cf0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
24d00 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
24d10 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
24d20 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
24d30 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
24d40 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
24d50 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
24d60 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
24d70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
24d80 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
24d90 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
24da0 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
24db0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
24dc0 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
24dd0 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
24de0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
24df0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
24e00 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
24e10 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
24e20 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
24e30 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
24e40 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
24e50 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
24e60 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
24e70 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
24e80 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
24e90 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
24ea0 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
24eb0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
24ec0 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
24ed0 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
24ee0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
24ef0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
24f00 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
24f10 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
24f20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
24f30 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
24f40 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
24f50 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
24f60 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
24f70 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
24f80 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
24f90 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
24fa0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
24fb0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
24fc0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
24fd0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
24fe0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
24ff0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
25000 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
25010 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
25020 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
25030 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
25040 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
25050 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
25060 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
25070 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
25080 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
25090 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
250a0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
250b0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
250c0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
250d0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
250e0 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
250f0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
25100 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
25110 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
25120 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
25130 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
25140 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
25150 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
25160 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
25170 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
25180 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
25190 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
251a0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
251b0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
251c0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
251d0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
251e0 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
251f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
25200 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
25210 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
25220 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
25230 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
25240 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25260 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
25270 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
25280 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
25290 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
252a0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
252b0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
252c0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
252d0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
252e0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
252f0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
25300 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
25310 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
25320 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
25330 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25340 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
25350 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
25360 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
25370 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
25380 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
25390 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
253a0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
253b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
253c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
253d0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
253e0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
253f0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
25400 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25410 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25420 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
25430 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
25440 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
25450 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25460 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
25470 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
25480 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
25490 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
254a0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
254b0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
254c0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
254d0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
254e0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
254f0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
25500 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
25510 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
25520 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
25530 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
25540 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
25550 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
25560 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
25570 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
25580 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
25590 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
255a0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
255b0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
255c0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
255d0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
255e0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
255f0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
25600 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
25610 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
25620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25630 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
25640 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
25650 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
25660 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
25670 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
25680 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
25690 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
256a0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
256b0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
256c0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
256d0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
256e0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
256f0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
25700 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
25710 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
25720 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
25730 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
25740 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
25750 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
25760 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
25770 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
25780 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
25790 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
257a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
257b0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
257c0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
257d0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
257e0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
257f0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
25800 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
25810 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
25820 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
25830 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25840 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
25850 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
25860 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
25870 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
25880 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
25890 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
258a0 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
258b0 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
258c0 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
258d0 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
258e0 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
258f0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
25900 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
25910 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
25920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
25930 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
25940 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
25950 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
25960 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
25970 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
25980 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
25990 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
259a0 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
259b0 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
259c0 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
259d0 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
259e0 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
259f0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
25a00 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
25a10 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
25a20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
25a30 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
25a40 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
25a50 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
25a60 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
25a70 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
25a80 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
25a90 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
25aa0 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
25ab0 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
25ac0 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
25ad0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
25ae0 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
25af0 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
25b00 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
25b10 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
25b20 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
25b30 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
25b40 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
25b50 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
25b60 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
25b70 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
25b80 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
25b90 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
25ba0 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
25bb0 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
25bc0 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
25bd0 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
25be0 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
25bf0 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
25c00 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
25c10 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
25c20 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
25c30 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
25c40 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
25c50 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
25c60 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
25c70 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
25c80 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
25c90 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
25ca0 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
25cb0 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
25cc0 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
25cd0 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
25ce0 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
25cf0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
25d00 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
25d10 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
25d20 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
25d30 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
25d40 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
25d50 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25d60 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
25d70 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25d80 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
25d90 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
25da0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
25db0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
25dc0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
25dd0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
25de0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
25df0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
25e00 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
25e10 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
25e20 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
25e30 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25e40 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
25e50 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
25e60 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
25e70 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
25e80 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
25e90 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
25ea0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
25eb0 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
25ec0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
25ed0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
25ee0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
25ef0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
25f00 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
25f10 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
25f20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
25f30 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
25f40 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
25f50 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
25f60 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
25f70 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
25f80 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
25f90 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
25fa0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
25fb0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
25fc0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
25fd0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
25fe0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
25ff0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
26000 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26010 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
26020 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
26030 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26040 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
26050 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
26060 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
26070 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
26080 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
26090 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
260a0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
260b0 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
260c0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
260d0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
260e0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
260f0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
26100 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
26110 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
26120 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
26130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
26140 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
26150 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
26160 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
26170 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
26180 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
26190 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
261a0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
261b0 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
261c0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
261d0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
261e0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
261f0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
26200 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
26210 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26220 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
26230 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
26240 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
26250 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
26260 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
26270 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26280 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
26290 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
262a0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
262b0 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
262c0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
262d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
262e0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
262f0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
26300 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
26310 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26320 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
26330 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
26340 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
26350 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
26360 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
26370 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
26380 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
26390 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
263a0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
263b0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
263c0 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
263d0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
263e0 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
263f0 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
26400 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
26410 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
26420 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
26430 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
26440 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
26450 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
26460 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
26470 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
26480 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26490 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
264a0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
264b0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
264c0 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
264d0 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
264e0 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
264f0 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
26500 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
26510 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
26520 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
26530 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
26540 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
26550 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
26560 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
26570 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
26580 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
26590 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
265a0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
265b0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
265c0 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
265d0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
265e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
265f0 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
26600 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
26610 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
26620 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
26630 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
26640 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
26650 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
26660 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
26670 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
26680 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
26690 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
266a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
266b0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
266c0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
266d0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
266e0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
266f0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
26700 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
26710 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
26720 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
26730 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
26740 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
26750 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
26760 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
26770 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
26780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26790 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
267a0 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
267b0 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
267c0 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
267d0 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
267e0 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
267f0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
26800 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26810 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
26820 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
26830 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
26840 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
26850 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
26860 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
26870 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
26880 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
26890 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54  ectory].*/.SQLIT
268a0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
268b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
268c0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
268d0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
268e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
268f0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26900 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26910 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26920 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26930 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
26940 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
26950 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
26960 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
26970 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
26980 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26990 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
269a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
269b0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
269c0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
269d0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
269e0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
269f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
26a00 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
26a10 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
26a20 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
26a30 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
26a40 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
26a50 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
26a60 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
26a70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
26a80 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
26a90 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
26aa0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
26ab0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
26ac0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
26ad0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
26ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
26af0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
26b00 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
26b10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
26b20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
26b30 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
26b40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
26b50 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
26b60 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
26b70 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
26b80 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
26b90 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
26ba0 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
26bb0 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
26bc0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
26bd0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
26be0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
26bf0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
26c00 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
26c10 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
26c20 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
26c30 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
26c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
26c50 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
26c60 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
26c70 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
26c80 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
26c90 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
26ca0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
26cb0 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
26cc0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
26cd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
26ce0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
26cf0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
26d00 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
26d10 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
26d20 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
26d30 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
26d40 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
26d50 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
26d60 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
26d70 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
26d80 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
26d90 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
26da0 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
26db0 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
26dc0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
26dd0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
26de0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
26df0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
26e00 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
26e10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26e20 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26e30 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
26e40 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
26e50 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
26e60 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
26e70 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
26e80 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
26e90 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
26ea0 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
26eb0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26ec0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
26ed0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
26ee0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
26ef0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
26f00 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
26f10 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
26f20 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
26f30 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
26f40 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
26f50 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
26f60 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
26f70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26f80 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
26f90 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
26fa0 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
26fb0 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
26fc0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
26fd0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
26fe0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
26ff0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
27000 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
27010 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
27020 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
27030 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
27040 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
27050 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
27060 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
27070 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
27080 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
27090 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
270a0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
270b0 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
270c0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
270d0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
270e0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
270f0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
27100 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
27110 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
27120 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
27130 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
27140 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
27150 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
27160 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
27170 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
27180 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
27190 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
271a0 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
271b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
271c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
271d0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
271e0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
271f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
27200 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27210 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
27220 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
27230 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
27240 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
27250 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
27260 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
27270 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
27280 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
27290 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
272a0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
272b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
272c0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
272d0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
272e0 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
272f0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
27300 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27310 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27320 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
27330 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
27340 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
27350 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
27360 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27370 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27380 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27390 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
273a0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
273b0 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
273c0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
273d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
273e0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
273f0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
27400 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
27410 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
27420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
27430 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
27440 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
27450 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
27460 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27470 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
27480 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
27490 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
274a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
274b0 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
274c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
274d0 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
274e0 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
274f0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
27500 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
27510 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
27520 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
27530 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
27540 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
27550 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
27560 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
27570 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
27580 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
27590 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
275a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
275b0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
275c0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
275d0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
275e0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
275f0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
27600 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
27610 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
27620 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
27630 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
27640 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
27650 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
27660 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
27670 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
27680 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
27690 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
276a0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
276b0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
276c0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
276d0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
276e0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
276f0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
27700 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
27710 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
27720 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
27730 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
27740 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
27750 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
27760 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
27770 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
27780 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
27790 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
277a0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
277b0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
277c0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
277d0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
277e0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
277f0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
27800 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
27810 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
27820 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
27830 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
27840 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
27850 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
27860 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27870 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27880 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27890 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
278a0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
278b0 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
278c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
278d0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
278e0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
278f0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
27900 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
27910 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
27920 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
27930 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
27940 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
27950 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
27960 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
27970 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
27980 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
27990 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
279a0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
279b0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
279c0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
279d0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
279e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
279f0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
27a00 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
27a10 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
27a20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
27a30 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
27a40 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
27a50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
27a60 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
27a70 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
27a80 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
27a90 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
27aa0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
27ab0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
27ac0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
27ad0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
27ae0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
27af0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
27b00 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
27b10 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
27b20 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
27b30 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
27b40 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
27b50 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
27b60 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
27b70 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
27b80 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
27b90 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
27ba0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
27bb0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
27bc0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
27bd0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
27be0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
27bf0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49   be set..*/.SQLI
27c00 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
27c10 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
27c20 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
27c30 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
27c40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
27c50 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78  DCALL sqlite3_ex
27c60 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
27c70 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
27c80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
27c90 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
27ca0 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  LL sqlite3_errms
27cb0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
27cc0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
27cd0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
27ce0 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  LL sqlite3_errms
27cf0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  g16(sqlite3*);.S
27d00 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27d10 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
27d20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
27d30 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
27d40 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
27d50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
27d60 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
27d70 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
27d80 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
27d90 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
27da0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
27db0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
27dc0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
27dd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27de0 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e  that.** has been
27df0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62   compiled into b
27e00 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69  inary form and i
27e10 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76  s ready to be ev
27e20 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  aluated..**.** T
27e30 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c  hink of each SQL
27e40 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20   statement as a 
27e50 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65  separate compute
27e60 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a  r program.  The.
27e70 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
27e80 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63  text is source c
27e90 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64  ode.  A prepared
27ea0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
27eb0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d  t .** is the com
27ec0 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64  piled object cod
27ed0 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74  e.  All SQL must
27ee0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
27ef0 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64  to a.** prepared
27f00 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72   statement befor
27f10 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e  e it can be run.
27f20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d  .**.** The life-
27f30 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61  cycle of a prepa
27f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
27f50 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65  ject usually goe
27f60 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  s like this:.**.
27f70 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
27f80 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61  Create the prepa
27f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
27fa0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
27fb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27fc0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  ]..** <li> Bind 
27fd0 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d  values to [param
27fe0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
27ff0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
28000 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
28010 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
28020 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
28030 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
28040 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
28050 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
28060 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61   Reset the prepa
28070 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
28080 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
28090 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
280a0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
280b0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
280c0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
280d0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
280e0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
280f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
28100 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
28110 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  l>.*/.typedef st
28120 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
28130 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
28140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28150 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
28160 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28170 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  te3.**.** ^(This
28180 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
28190 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
281a0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
281b0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
281c0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
281d0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
281e0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
281f0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
28200 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
28210 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
28220 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
28230 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
28240 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
28250 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
28260 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
28270 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
28280 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
28290 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
282a0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
282b0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
282c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
282d0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
282e0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
282f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
28300 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
28310 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
28320 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
28330 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
28340 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
28350 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
28360 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
28370 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
28380 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
28390 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
283a0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
283b0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
283c0 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
283d0 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
283e0 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
283f0 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
28400 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
28410 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
28420 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
28430 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
28440 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
28450 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
28460 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
28470 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
28480 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
28490 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
284a0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
284b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
284c0 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
284d0 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
284e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
284f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
28500 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
28510 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
28520 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
28530 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
28540 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
28550 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
28560 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
28570 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
28580 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
28590 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
285a0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
285b0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
285c0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
285d0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
285e0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
285f0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
28600 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
28610 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
28620 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
28630 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
28640 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
28650 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
28660 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
28670 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
28680 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
28690 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
286a0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
286b0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
286c0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
286d0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
286e0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
286f0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
28700 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
28710 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
28720 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
28730 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
28740 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
28750 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
28760 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
28770 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
28780 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
28790 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
287a0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
287b0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
287c0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
287d0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
287e0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
287f0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
28800 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
28810 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
28820 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
28830 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
28840 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
28850 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
28860 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
28870 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
28880 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
28890 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
288a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
288b0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
288c0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
288d0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
288e0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
288f0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
28900 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
28910 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28920 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
28930 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
28940 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
28950 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
28960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
28970 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
28980 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
28990 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
289a0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
289b0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
289c0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
289d0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
289e0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
289f0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
28a00 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
28a10 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
28a20 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
28a30 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
28a40 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
28a50 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
28a60 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
28a70 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
28a80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
28a90 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
28aa0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
28ab0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
28ac0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
28ad0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
28ae0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28af0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
28b00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28b10 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
28b20 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
28b30 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
28b40 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
28b50 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28b60 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
28b70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28b80 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
28b90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28ba0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
28bb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
28bc0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
28bd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28be0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
28bf0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28c00 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
28c10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28c20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28c30 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
28c40 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
28c50 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
28c60 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
28c70 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
28c80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
28c90 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
28ca0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
28cb0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
28cc0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
28cd0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28ce0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
28cf0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28d00 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
28d10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28d20 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
28d30 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
28d40 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
28d50 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28d60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
28d70 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
28d80 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
28d90 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
28da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28db0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28dc0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
28dd0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
28de0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
28df0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28e00 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
28e10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28e20 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
28e30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28e40 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
28e50 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
28e60 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
28e70 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
28e80 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
28e90 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
28ea0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
28eb0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
28ec0 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
28ed0 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
28ee0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
28ef0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
28f00 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
28f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28f20 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
28f30 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28f40 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
28f50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
28f60 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
28f70 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
28f80 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
28f90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28fa0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
28fb0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28fc0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
28fd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28fe0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
28ff0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
29000 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
29010 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
29020 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
29030 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
29040 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
29050 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
29060 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
29070 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29080 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
29090 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
290a0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
290b0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
290c0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
290d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
290e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
290f0 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
29100 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29110 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
29120 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
29130 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
29140 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
29150 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
29160 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
29170 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29180 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
29190 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
291a0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
291b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
291c0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
291d0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
291e0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
291f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29200 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29210 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
29220 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29230 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
29240 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29250 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
29260 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
29270 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
29280 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29290 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
292a0 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
292b0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
292c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
292d0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
292e0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
292f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
29300 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
29310 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
29320 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
29330 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
29340 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
29350 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29360 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
29370 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
29380 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29390 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
293a0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
293b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
293c0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
293d0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
293e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
293f0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
29400 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
29410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29420 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
29430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
29440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29450 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29460 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
29470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29480 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29490 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
294a0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
294b0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
294c0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
294d0 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
294e0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
294f0 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
29500 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
29510 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
29520 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
29530 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
29540 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
29550 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
29560 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
29570 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
29580 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
29590 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
295a0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
295b0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
295c0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
295d0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
295e0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
295f0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
29600 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29610 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
29620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29630 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
29640 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
29650 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
29660 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
29670 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
29680 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
29690 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
296a0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
296b0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
296c0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
296d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
296e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
296f0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
29700 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
29710 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
29720 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
29730 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
29740 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
29750 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
29760 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
29770 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
29780 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
29790 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
297a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
297b0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
297c0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
297d0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
297e0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
297f0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
29800 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
29810 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
29820 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
29830 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
29840 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
29850 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29860 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
29870 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
29880 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
29890 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
298a0 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
298b0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
298c0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
298d0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
298e0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
298f0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
29900 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
29910 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
29920 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
29930 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
29940 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
29950 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29960 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
29970 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
29980 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
29990 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
299a0 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
299b0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
299c0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
299d0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
299e0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
299f0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
29a00 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
29a10 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
29a20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
29a30 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
29a40 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
29a50 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
29a60 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
29a70 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
29a80 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
29a90 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
29aa0 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
29ab0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
29ac0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
29ad0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
29ae0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
29af0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
29b00 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
29b10 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
29b20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
29b30 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
29b40 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
29b50 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
29b60 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
29b70 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
29b80 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
29b90 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
29ba0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
29bb0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
29bc0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
29bd0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
29be0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
29bf0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
29c00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29c10 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
29c20 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
29c30 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
29c40 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
29c50 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
29c60 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
29c70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
29c80 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
29c90 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
29ca0 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
29cb0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
29cc0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
29cd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29ce0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
29cf0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
29d00 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
29d10 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
29d20 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
29d30 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
29d40 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
29d50 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
29d60 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
29d70 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
29d80 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
29d90 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
29da0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
29db0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
29dc0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29dd0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
29de0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
29df0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
29e00 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
29e10 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
29e20 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
29e30 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
29e40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
29e50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
29e60 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
29e70 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
29e80 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
29e90 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
29ea0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
29eb0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
29ec0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
29ed0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
29ee0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
29ef0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
29f00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
29f10 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
29f20 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
29f30 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
29f40 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
29f50 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
29f60 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
29f70 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
29f80 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
29f90 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
29fa0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
29fb0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
29fc0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
29fd0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
29fe0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
29ff0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2a000 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2a010 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2a020 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2a030 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2a040 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2a050 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2a060 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2a070 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2a080 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2a090 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2a0a0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2a0b0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2a0c0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2a0d0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2a0e0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2a0f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a100 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2a110 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2a120 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2a130 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2a140 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2a150 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2a160 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2a170 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2a180 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2a190 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2a1a0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2a1b0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2a1c0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2a1d0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2a1e0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2a1f0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2a200 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2a210 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2a220 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2a230 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2a240 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2a250 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2a260 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2a270 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2a280 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2a290 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2a2a0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2a2b0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2a2c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2a2d0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2a2e0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2a2f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2a300 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2a310 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2a320 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2a330 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2a340 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2a350 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2a360 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2a370 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2a380 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2a390 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2a3a0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2a3b0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2a3c0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2a3d0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2a3e0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2a3f0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2a400 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2a410 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2a420 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2a430 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2a440 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2a450 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
2a460 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2a470 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2a480 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
2a490 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a4a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a4b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a4c0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2a4d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a4e0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2a4f0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a500 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a510 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a520 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a530 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a540 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a550 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a560 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a570 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2a580 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a590 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a5a0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a5b0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a5c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2a5d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
2a5e0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2a5f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a600 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a610 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a620 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2a630 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a640 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2a650 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a660 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a670 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a680 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a690 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a6a0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a6b0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a6c0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a6d0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2a6e0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a6f0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a700 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a710 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a720 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2a730 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
2a740 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
2a750 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a760 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a770 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a780 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2a790 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a7a0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2a7b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a7c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a7d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a7e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a7f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a800 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a810 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a820 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a830 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2a840 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a850 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a860 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a870 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
2a880 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2a890 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65  CALL sqlite3_pre
2a8a0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
2a8b0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a8c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a8d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a8e0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2a8f0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a900 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2a910 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2a920 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2a930 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2a940 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2a950 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2a960 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2a970 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2a980 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2a990 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
2a9a0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2a9b0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2a9c0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2a9d0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
2a9e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
2a9f0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
2aa00 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  SQL.** METHOD: s
2aa10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2aa20 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2aa30 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2aa40 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
2aa50 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
2aa60 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
2aa70 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
2aa80 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2aa90 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
2aaa0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
2aab0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
2aac0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2aad0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2aae0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2aaf0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  re16_v2()]..*/.S
2ab00 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2ab10 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2ab20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c  CALL sqlite3_sql
2ab30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ab40 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ab50 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2ab60 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2ab70 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2ab80 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2ab90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2aba0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2abb0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2abc0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2abd0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2abe0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2abf0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2ac00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac10 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2ac20 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2ac30 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2ac40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2ac50 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2ac60 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2ac70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2ac80 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2ac90 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2aca0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2acb0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2acc0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2acd0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2ace0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2acf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2ad00 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2ad10 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2ad20 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2ad30 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2ad40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2ad50 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2ad60 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2ad70 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2ad80 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2ad90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2ada0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2adb0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2adc0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2add0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2ade0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2adf0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2ae00 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2ae10 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2ae20 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2ae30 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2ae40 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2ae50 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2ae60 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2ae70 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2ae80 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2ae90 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2aea0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2aeb0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2aec0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2aed0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2aee0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2aef0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2af00 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2af10 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2af20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2af30 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2af40 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2af50 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2af60 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2af70 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2af80 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2af90 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2afa0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2afb0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2afc0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2afd0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2afe0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2aff0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2b000 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2b010 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2b020 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2b030 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2b040 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2b050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b060 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2b070 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2b080 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2b090 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2b0a0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
2b0b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2b0c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b0d0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b0e0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
2b0f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b100 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2b110 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
2b120 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
2b130 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
2b140 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2b150 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2b160 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2b170 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
2b180 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2b190 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
2b1a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b1b0 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
2b1c0 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
2b1d0 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
2b1e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b1f0 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
2b200 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2b210 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
2b220 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
2b230 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2b240 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
2b250 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2b260 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
2b270 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
2b280 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
2b290 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
2b2a0 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
2b2b0 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
2b2c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2b2d0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
2b2e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2b2f0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
2b300 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b310 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2b320 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
2b330 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
2b340 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2b350 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
2b360 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2b370 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
2b380 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
2b390 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
2b3a0 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
2b3b0 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
2b3c0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
2b3d0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
2b3e0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
2b3f0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
2b400 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
2b410 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
2b420 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
2b430 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
2b440 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
2b450 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
2b460 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  ion open..*/.SQL
2b470 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b480 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b490 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
2b4a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2b4b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
2b4c0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
2b4d0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
2b4e0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
2b4f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b500 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
2b510 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
2b520 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
2b530 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
2b540 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
2b550 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
2b560 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
2b570 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
2b580 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
2b590 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2b5a0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
2b5b0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
2b5c0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
2b5d0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
2b5e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
2b5f0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
2b600 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
2b610 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
2b620 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
2b630 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
2b640 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b650 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
2b660 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
2b670 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
2b680 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
2b690 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
2b6a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b6b0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
2b6c0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
2b6d0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
2b6e0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
2b6f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b700 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
2b710 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
2b720 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
2b730 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
2b740 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
2b750 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
2b760 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
2b770 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b780 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
2b790 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
2b7a0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2b7b0 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72  e used to constr
2b7c0 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72  uct a new .** pr
2b7d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b7e0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e  value from an un
2b7f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b800 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
2b810 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
2b820 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
2b830 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
2b840 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
2b850 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
2b860 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
2b870 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2b880 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
2b890 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b8a0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
2b8b0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2b8c0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
2b8d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b8e0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
2b8f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
2b900 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
2b910 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
2b920 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2b930 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
2b940 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2b950 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
2b960 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
2b970 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
2b980 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
2b990 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
2b9a0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2b9b0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
2b9c0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2b9d0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
2b9e0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
2b9f0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2ba00 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2ba10 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2ba20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2ba30 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
2ba40 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
2ba50 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
2ba60 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
2ba70 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
2ba80 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
2ba90 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
2baa0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
2bab0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
2bac0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2bad0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2bae0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2baf0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
2bb00 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
2bb10 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
2bb20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bb30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
2bb40 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
2bb50 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
2bb60 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
2bb70 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
2bb80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2bb90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
2bba0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
2bbb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2bbc0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
2bbd0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2bbe0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2bbf0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
2bc00 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
2bc10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2bc20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
2bc30 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
2bc40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2bc50 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2bc60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2bc70 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
2bc80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2bc90 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
2bca0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
2bcb0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2bcc0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
2bcd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bce0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
2bcf0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
2bd00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
2bd10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bd20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
2bd30 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
2bd40 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
2bd50 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
2bd60 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
2bd70 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
2bd80 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
2bd90 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
2bda0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
2bdb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2bdc0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
2bdd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2bde0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
2bdf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2be00 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
2be10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2be20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2be30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2be40 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
2be50 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
2be60 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
2be70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2be80 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
2be90 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
2bea0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2beb0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
2bec0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2bed0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
2bee0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2bef0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
2bf00 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
2bf10 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
2bf20 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
2bf30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2bf40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2bf50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
2bf60 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2bf70 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
2bf80 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
2bf90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
2bfa0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
2bfb0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
2bfc0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
2bfd0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
2bfe0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2bff0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
2c000 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
2c010 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2c020 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2c030 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c040 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2c050 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2c060 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2c070 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2c080 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2c090 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2c0a0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2c0b0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2c0c0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2c0d0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2c0e0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2c0f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2c100 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2c110 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2c120 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2c130 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2c140 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2c150 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2c160 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2c170 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2c180 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2c190 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2c1a0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2c1b0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2c1c0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2c1d0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2c1e0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2c1f0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2c200 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2c210 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2c220 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2c230 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2c240 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2c250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2c260 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2c270 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2c280 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2c290 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2c2a0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2c2b0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2c2c0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2c2d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c2e0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2c2f0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2c300 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2c310 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2c320 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2c330 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2c340 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2c350 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2c360 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2c370 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2c380 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2c390 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2c3a0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2c3b0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2c3c0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2c3d0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2c3e0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2c3f0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2c400 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2c410 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2c420 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2c430 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2c440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c450 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c460 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2c470 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2c480 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2c490 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2c4a0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2c4b0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2c4c0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2c4d0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2c4e0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2c4f0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2c500 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2c510 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2c520 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2c530 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2c540 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2c550 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2c560 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2c570 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2c580 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2c590 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2c5a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2c5b0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2c5c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2c5d0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2c5e0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2c5f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2c600 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2c610 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2c620 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2c630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2c640 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2c650 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2c660 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2c670 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2c680 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2c690 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c6a0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2c6b0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2c6c0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2c6d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2c6e0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2c6f0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2c700 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2c710 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2c720 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2c730 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2c740 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2c750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c760 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2c770 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2c780 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2c790 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2c7a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2c7b0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2c7c0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2c7d0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2c7e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c7f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2c800 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2c810 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2c820 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2c830 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2c840 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2c850 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2c860 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2c870 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2c880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c890 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2c8a0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2c8b0 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2c8c0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2c8d0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2c8e0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2c8f0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2c900 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2c910 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2c920 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2c930 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2c940 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2c950 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2c960 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2c970 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2c980 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2c990 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2c9a0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2c9b0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2c9c0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2c9d0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2c9e0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2c9f0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2ca00 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2ca10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2ca20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2ca30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ca40 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2ca50 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2ca60 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2ca70 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2ca80 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2ca90 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2caa0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2cab0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2cac0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2cad0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2cae0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2caf0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2cb00 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2cb10 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2cb20 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2cb30 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2cb40 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2cb50 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2cb60 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2cb70 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2cb80 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2cb90 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2cba0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2cbb0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2cbc0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2cbd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2cbe0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2cbf0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2cc00 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2cc10 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2cc20 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2cc30 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2cc40 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2cc50 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2cc60 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2cc70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2cc80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2cc90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2cca0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2ccb0 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2ccc0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2ccd0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2cce0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2ccf0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2cd00 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2cd10 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2cd20 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2cd30 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2cd40 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2cd50 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2cd60 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2cd70 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2cd80 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2cd90 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2cda0 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2cdb0 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2cdc0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2cdd0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2cde0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2cdf0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2ce00 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2ce10 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2ce20 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2ce30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2ce40 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2ce50 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2ce60 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2ce70 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2ce80 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2ce90 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2cea0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2ceb0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2cec0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2ced0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2cee0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2cef0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2cf00 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2cf10 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2cf20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2cf30 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2cf40 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2cf50 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2cf60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2cf70 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2cf80 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2cf90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2cfa0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2cfb0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2cfc0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2cfd0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2cfe0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2cff0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2d000 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2d010 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2d020 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2d030 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2d040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2d050 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2d060 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2d070 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2d080 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2d090 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2d0a0 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2d0b0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2d0c0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2d0d0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2d0e0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2d0f0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2d100 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2d110 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2d120 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d130 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2d140 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2d150 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2d160 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2d170 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2d180 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2d190 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2d1a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d1b0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2d1c0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2d1d0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2d1e0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2d1f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2d200 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2d210 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2d220 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2d230 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2d240 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2d250 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2d260 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2d270 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2d280 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2d290 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2d2a0 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2d2b0 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2d2c0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2d2d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2d2e0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2d2f0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2d300 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2d310 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2d320 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2d330 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2d340 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2d350 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2d360 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2d370 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2d380 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2d390 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2d3a0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2d3b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2d3c0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2d3d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2d3e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2d3f0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2d400 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2d410 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2d420 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2d430 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2d440 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2d450 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d460 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d470 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d490 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2d4a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2d4b0 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2d4c0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2d4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2d4e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2d4f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2d500 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d510 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
2d520 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d530 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  nt, double);.SQL
2d540 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2d550 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d560 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2d570 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d580 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d590 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d5a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d5b0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d5c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2d5d0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
2d5e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d5f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d600 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2d610 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2d620 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d630 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d640 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2d650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d660 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2d670 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2d680 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d690 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d6a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d6b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2d6c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2d6d0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2d6e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2d6f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2d700 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d710 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2d720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d730 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2d740 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2d750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d760 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2d770 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2d780 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2d790 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d7a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d7b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2d7c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d7d0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2d7e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2d7f0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2d800 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d810 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2d820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d830 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2d840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2d850 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2d860 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2d870 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d880 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2d890 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2d8a0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2d8b0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2d8c0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2d8d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d8e0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2d8f0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2d900 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2d910 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2d920 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2d930 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2d940 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2d950 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2d960 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2d970 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2d980 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2d990 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2d9a0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2d9b0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2d9c0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2d9d0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2d9e0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2d9f0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2da00 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2da10 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2da20 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2da30 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2da40 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2da50 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2da60 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2da70 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2da80 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2da90 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2daa0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2dab0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2dac0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2dad0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2dae0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2daf0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2db00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2db10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2db20 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2db30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2db40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2db50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2db60 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2db70 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2db80 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2db90 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2dba0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2dbb0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2dbc0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2dbd0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2dbe0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2dbf0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2dc00 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2dc10 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2dc20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2dc30 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2dc40 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2dc50 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2dc60 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2dc70 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2dc80 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2dc90 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2dca0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2dcb0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2dcc0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2dcd0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2dce0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2dcf0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2dd00 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2dd10 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2dd20 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2dd30 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2dd40 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2dd50 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2dd60 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2dd70 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2dd80 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2dd90 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2dda0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2ddb0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2ddc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ddd0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2dde0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2ddf0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2de00 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2de10 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2de20 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2de30 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2de40 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2de50 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2de60 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2de70 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2de80 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2de90 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2dea0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2deb0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2dec0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2ded0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2dee0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2def0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2df00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2df10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2df20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2df30 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2df40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2df50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2df60 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2df70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2df80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2df90 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2dfa0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2dfb0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2dfc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2dfd0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2dfe0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2dff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2e000 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2e010 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2e020 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2e030 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e040 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2e050 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2e060 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2e070 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2e080 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2e090 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2e0a0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2e0b0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2e0c0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2e0d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e0e0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2e0f0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2e100 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2e110 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2e120 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2e130 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2e140 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2e150 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2e160 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2e170 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2e180 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2e190 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2e1a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e1b0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2e1c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e1d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e1e0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e1f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e200 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2e210 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e220 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2e230 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2e240 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2e250 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e260 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2e270 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2e280 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2e290 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2e2a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2e2b0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2e2c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2e2d0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2e2e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e2f0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2e300 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2e310 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2e320 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2e330 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2e340 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e350 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2e360 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2e370 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2e380 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2e390 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2e3a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2e3b0 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
2e3c0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2e3d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c  DCALL sqlite3_cl
2e3e0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2e3f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2e400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2e410 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2e420 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2e430 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e440 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2e450 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2e460 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2e470 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2e480 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2e490 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e4a0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2e4b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2e4c0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2e4d0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2e4e0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2e4f0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2e500 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2e510 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2e520 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2e530 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  a_count()].*/.SQ
2e540 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2e550 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2e560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2e570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2e580 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2e590 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2e5a0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2e5b0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2e5c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e5d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2e5e0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2e5f0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2e600 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2e610 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2e620 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2e630 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2e640 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2e650 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2e660 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e670 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2e680 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2e690 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2e6a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2e6b0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2e6c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e6d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2e6e0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2e6f0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2e700 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2e710 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2e720 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2e730 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2e740 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2e750 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2e760 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2e770 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2e780 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2e790 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2e7a0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2e7b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2e7c0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2e7d0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2e7e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e7f0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2e800 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2e810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2e820 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2e830 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2e840 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2e850 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2e860 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2e870 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2e880 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2e890 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2e8a0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2e8b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2e8c0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2e8d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2e8e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2e8f0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2e900 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2e910 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2e920 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2e930 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2e940 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2e950 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2e960 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2e970 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2e980 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2e990 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2e9a0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2e9b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2e9c0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2e9d0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2e9e0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2e9f0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2ea00 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2ea10 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2ea20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2ea30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2ea40 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2ea50 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2ea60 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2ea70 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2ea80 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2ea90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2eaa0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2eab0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2eac0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2ead0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2eae0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2eaf0 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2eb00 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2eb10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2eb20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2eb30 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2eb40 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2eb50 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2eb60 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2eb70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2eb80 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2eb90 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2eba0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2ebb0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2ebc0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2ebd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2ebe0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2ebf0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2ec00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2ec10 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2ec20 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2ec30 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2ec40 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2ec50 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2ec60 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2ec70 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2ec80 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2ec90 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2eca0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2ecb0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2ecc0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2ecd0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2ece0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2ecf0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2ed00 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2ed10 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2ed20 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2ed30 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2ed40 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2ed50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ed60 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2ed70 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2ed80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ed90 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2eda0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2edb0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2edc0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2edd0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2ede0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2edf0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2ee00 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2ee10 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2ee20 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2ee30 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2ee40 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2ee50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2ee60 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2ee70 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2ee80 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2ee90 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2eea0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2eeb0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2eec0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2eed0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2eee0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2eef0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2ef00 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2ef10 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2ef20 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2ef30 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2ef40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2ef50 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2ef60 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2ef70 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2ef80 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2ef90 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2efa0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2efb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2efc0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2efd0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2efe0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2eff0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2f000 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2f010 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2f020 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2f030 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2f040 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2f050 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2f060 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2f070 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2f080 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2f090 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2f0a0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2f0b0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2f0c0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2f0d0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2f0e0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2f0f0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2f100 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2f110 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2f120 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2f130 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2f140 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2f150 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2f160 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2f170 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2f180 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2f190 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2f1a0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2f1b0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2f1c0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2f1d0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2f1e0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2f1f0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2f200 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2f210 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2f220 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2f230 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2f240 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2f250 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2f260 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2f270 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2f280 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2f290 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2f2a0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2f2b0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2f2c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2f2d0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2f2e0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2f2f0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2f300 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2f310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2f320 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2f330 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2f340 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2f350 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2f360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2f370 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2f380 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2f390 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2f3a0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2f3b0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
2f3c0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2f3d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2f3e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f3f0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
2f400 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2f410 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f420 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
2f430 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2f440 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2f450 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f460 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2f470 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2f480 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2f490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2f4a0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2f4b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2f4c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2f4d0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2f4e0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f4f0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2f500 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f510 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f520 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2f530 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f540 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2f550 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2f560 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2f570 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2f580 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2f590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2f5a0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2f5b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2f5c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f5d0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2f5e0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2f5f0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2f600 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f610 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
2f620 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
2f630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f640 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
2f650 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
2f660 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
2f670 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
2f680 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
2f690 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
2f6a0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
2f6b0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
2f6c0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
2f6d0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2f6e0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
2f6f0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
2f700 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
2f710 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
2f720 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
2f730 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2f740 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
2f750 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2f760 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
2f770 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2f780 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
2f790 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2f7a0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
2f7b0 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
2f7c0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2f7d0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
2f7e0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
2f7f0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
2f800 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
2f810 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
2f820 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
2f830 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
2f840 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
2f850 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
2f860 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
2f870 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
2f880 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
2f890 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
2f8a0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
2f8b0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
2f8c0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
2f8d0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
2f8e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
2f8f0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
2f900 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2f910 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
2f920 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
2f930 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
2f940 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
2f950 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
2f960 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
2f970 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
2f980 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
2f990 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
2f9a0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
2f9b0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
2f9c0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
2f9d0 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
2f9e0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
2f9f0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
2fa00 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
2fa10 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
2fa20 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
2fa30 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
2fa40 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
2fa50 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
2fa60 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2fa70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2fa80 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2fa90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2faa0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2fab0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2fac0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2fad0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2fae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2faf0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2fb00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2fb10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2fb20 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2fb30 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2fb40 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2fb50 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2fb60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fb70 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2fb80 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2fb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2fba0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2fbb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2fbc0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2fbd0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2fbe0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2fbf0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2fc00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fc10 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2fc20 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2fc30 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2fc40 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2fc50 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2fc60 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2fc70 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2fc80 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2fc90 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2fca0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2fcb0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2fcc0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2fcd0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2fce0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2fcf0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2fd00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2fd10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2fd20 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2fd30 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2fd40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2fd50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2fd60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2fd70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2fd80 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2fd90 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2fda0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2fdb0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2fdc0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2fdd0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2fde0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2fdf0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2fe00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2fe10 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2fe20 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2fe30 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2fe40 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2fe50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2fe60 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2fe70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2fe80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2fe90 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2fea0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2feb0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2fec0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2fed0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2fee0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2fef0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2ff00 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2ff10 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2ff20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2ff30 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2ff40 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2ff50 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2ff60 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2ff70 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2ff80 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2ff90 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2ffa0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2ffb0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2ffc0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2ffd0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2ffe0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2fff0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
30000 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
30010 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
30020 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
30030 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
30040 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
30050 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
30060 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
30070 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
30080 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
30090 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
300a0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
300b0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
300c0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
300d0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
300e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
300f0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
30100 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
30110 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
30120 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
30130 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
30140 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
30150 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
30160 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
30170 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30180 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
30190 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
301a0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
301b0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
301c0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
301d0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
301e0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
301f0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
30200 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
30210 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
30220 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
30230 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
30240 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
30250 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
30260 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
30270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
30280 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
30290 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
302a0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
302b0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
302c0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
302d0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
302e0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
302f0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
30300 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
30310 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
30320 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
30330 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
30340 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
30350 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
30360 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
30370 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30380 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
30390 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
303a0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
303b0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
303c0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
303d0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
303e0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
303f0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
30400 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
30410 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
30420 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
30430 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
30440 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
30450 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
30460 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
30470 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
30480 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
30490 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
304a0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
304b0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
304c0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
304d0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
304e0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
304f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
30500 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
30510 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
30520 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
30530 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
30540 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
30550 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
30560 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
30570 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
30580 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
30590 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
305a0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
305b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
305c0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
305d0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
305e0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
305f0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30610 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
30620 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
30630 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
30640 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
30650 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
30660 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
30670 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
30680 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
30690 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
306a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
306b0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
306c0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
306d0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
306e0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
306f0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
30700 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
30710 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
30720 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
30730 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
30740 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
30750 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
30760 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
30770 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
30780 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
30790 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
307a0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
307b0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
307c0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
307d0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
307e0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
307f0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
30800 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
30810 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
30820 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
30830 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
30840 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
30850 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
30860 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
30870 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
30880 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
30890 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
308a0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
308b0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
308c0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
308d0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
308e0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
308f0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
30900 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
30910 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
30920 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
30930 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
30940 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
30950 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
30960 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
30970 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
30980 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
30990 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
309a0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
309b0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
309c0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
309d0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
309e0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
309f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
30a00 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
30a10 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
30a20 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
30a30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
30a40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
30a50 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
30a60 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
30a70 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
30a80 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
30a90 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
30aa0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
30ab0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
30ac0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
30ad0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
30ae0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
30af0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
30b00 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
30b10 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
30b20 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
30b30 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
30b40 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
30b50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
30b60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30b70 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
30b80 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
30b90 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
30ba0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
30bb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30bc0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
30bd0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
30be0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
30bf0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
30c00 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
30c10 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
30c20 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
30c30 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
30c40 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
30c50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
30c60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
30c70 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  L sqlite3_step(s
30c80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
30c90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30ca0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
30cb0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
30cc0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
30cd0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30ce0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
30cf0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
30d00 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
30d10 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
30d20 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
30d30 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
30d40 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
30d50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30d60 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
30d70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30d80 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
30d90 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
30da0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
30db0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
30dc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
30dd0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
30de0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
30df0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
30e00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30e10 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
30e20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
30e30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
30e40 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
30e50 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
30e60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
30e70 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
30e80 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
30e90 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
30ea0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
30eb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
30ec0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
30ed0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
30ee0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
30ef0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
30f00 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
30f10 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
30f20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30f30 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
30f40 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
30f50 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
30f60 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
30f70 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
30f80 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
30f90 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
30fa0 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
30fb0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
30fc0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
30fd0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
30fe0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
30ff0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
31000 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
31010 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
31020 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
31030 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
31040 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31050 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
31060 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
31070 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
31080 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
31090 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
310a0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
310b0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
310c0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
310d0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
310e0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
310f0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
31100 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
31110 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
31120 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
31130 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
31140 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
31150 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
31160 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
31170 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
31180 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
31190 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
311a0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
311b0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
311c0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
311d0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
311e0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
311f0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
31200 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
31210 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
31220 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
31230 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
31240 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
31250 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
31260 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
31270 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
31280 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
31290 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
312a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
312b0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
312c0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
312d0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
312e0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
312f0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
31300 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
31310 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
31320 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
31330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
31340 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
31350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
31360 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
31370 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
31380 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
31390 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
313a0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
313b0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
313c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
313d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
313e0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
313f0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
31400 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
31410 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
31420 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
31430 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
31440 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
31450 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
31460 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
31470 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
31480 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
31490 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
314a0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
314b0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
314c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
314d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
314e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
314f0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
31500 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
31510 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
31520 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
31530 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
31540 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
31550 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
31560 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
31570 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
31580 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
31590 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
315a0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
315b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
315c0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
315d0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
315e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
315f0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
31600 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
31610 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
31620 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
31630 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
31640 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
31650 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
31660 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
31670 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
31680 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
31690 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
316a0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
316b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
316c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
316d0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
316e0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
316f0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
31700 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31710 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
31720 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
31730 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
31740 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
31750 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
31760 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
31770 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
31780 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
31790 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
317a0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
317b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
317c0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
317d0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
317e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
317f0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
31800 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
31810 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
31820 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
31830 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
31840 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31850 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
31860 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
31870 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
31880 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
31890 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
318a0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
318b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
318c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
318d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
318e0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
318f0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
31900 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
31910 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
31920 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
31930 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
31940 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
31950 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
31960 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
31970 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
31980 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
31990 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
319a0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
319b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
319c0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
319d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
319e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
319f0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
31a00 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
31a10 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
31a20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
31a30 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
31a40 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
31a50 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
31a60 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
31a70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31a80 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
31a90 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
31aa0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
31ab0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
31ac0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
31ad0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
31ae0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
31af0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
31b00 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
31b10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31b20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
31b30 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
31b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31b50 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
31b60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31b70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
31b80 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
31b90 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31ba0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
31bb0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
31bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31bd0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
31be0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
31bf0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
31c00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
31c10 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
31c20 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
31c30 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
31c40 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
31c50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
31c60 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
31c70 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
31c80 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
31c90 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
31ca0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
31cb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
31cc0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
31cd0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
31ce0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
31cf0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
31d00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
31d10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
31d20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31d30 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
31d40 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
31d50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
31d60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
31d70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31d80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31d90 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
31da0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
31db0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
31dc0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
31dd0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
31de0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
31df0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
31e00 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
31e10 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
31e20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31e30 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
31e40 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
31e50 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
31e60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31e70 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
31e80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
31e90 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
31ea0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
31eb0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
31ec0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
31ed0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31ee0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
31ef0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31f00 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
31f10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31f20 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
31f30 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
31f40 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
31f50 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
31f60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
31f70 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
31f80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31f90 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
31fa0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
31fb0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
31fc0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
31fd0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
31fe0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
31ff0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
32000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32010 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
32020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32030 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
32040 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
32050 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
32060 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
32070 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
32080 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
32090 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
320a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
320b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
320c0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
320d0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
320e0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
320f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
32100 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
32110 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
32120 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
32130 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
32140 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
32150 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
32160 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
32170 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
32180 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
32190 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
321a0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
321b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
321c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
321d0 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
321e0 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
321f0 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
32200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
32210 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
32220 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
32230 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
32240 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
32250 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32260 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
32270 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
32280 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32290 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
322a0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
322b0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
322c0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
322d0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
322e0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
322f0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
32300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
32310 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
32320 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
32330 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
32340 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
32350 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
32360 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a  threadsafe..**.*
32370 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32380 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
32390 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
323a0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
323b0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
323c0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
323d0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
323e0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
323f0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
32400 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
32410 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
32420 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
32430 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
32440 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
32450 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
32460 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
32470 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
32480 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
32490 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
324a0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
324b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
324c0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
324d0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
324e0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
324f0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
32500 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
32510 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
32520 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
32530 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
32540 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
32550 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
32560 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
32570 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
32580 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
32590 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
325a0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
325b0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
325c0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
325d0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
325e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
325f0 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
32600 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
32610 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
32620 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
32630 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
32640 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
32650 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
32660 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
32670 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
32680 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
32690 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
326a0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
326b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
326c0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
326d0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
326e0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
326f0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
32700 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
32710 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
32720 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
32730 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
32740 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
32750 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
32760 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
32770 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
32780 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
32790 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
327a0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
327b0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
327c0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
327d0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
327e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
327f0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
32800 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
32810 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
32820 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
32830 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
32840 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
32850 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
32860 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
32870 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
32880 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
32890 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
328a0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
328b0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
328c0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
328d0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
328e0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
328f0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
32900 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
32910 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
32920 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
32930 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
32940 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
32950 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
32960 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32970 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
32980 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
32990 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
329a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
329b0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
329c0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
329d0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
329e0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
329f0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
32a00 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
32a10 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
32a20 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
32a30 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
32a40 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
32a50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32a60 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
32a70 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
32a80 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
32a90 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
32aa0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
32ab0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
32ac0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
32ad0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
32ae0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32af0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
32b00 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
32b10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32b20 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
32b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32b40 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
32b50 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
32b60 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
32b70 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
32b80 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
32b90 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
32ba0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
32bb0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
32bc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
32bd0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
32be0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
32bf0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
32c00 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
32c10 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
32c20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
32c30 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
32c40 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
32c50 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
32c60 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
32c70 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
32c80 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
32c90 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
32ca0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
32cb0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
32cc0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
32cd0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
32ce0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
32cf0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
32d00 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
32d10 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
32d20 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
32d30 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
32d40 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
32d50 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
32d60 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
32d70 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
32d80 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
32d90 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
32da0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
32db0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
32dc0 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74  fest policy is t
32dd0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
32de0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
32df0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
32e00 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
32e10 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
32e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32e30 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
32e40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32e50 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
32e60 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
32e70 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
32e80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32e90 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
32ea0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
32eb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
32ec0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
32ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32ee0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
32ef0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
32f00 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
32f10 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
32f20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
32f30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
32f40 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
32f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32f60 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
32f70 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
32f80 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
32f90 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
32fa0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
32fb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
32fc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
32fd0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
32fe0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
32ff0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
33000 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
33010 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
33020 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
33030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33040 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
33050 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
33060 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
33070 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
33080 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
33090 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
330a0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
330b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
330c0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
330d0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
330e0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
330f0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
33100 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
33110 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
33120 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
33130 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
33140 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
33150 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
33160 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
33170 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
33180 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
33190 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
331a0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
331b0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
331c0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e  cally.  Do <em>n
331d0 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65  ot</em> pass the
331e0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
331f0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
33210 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
33220 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
33230 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
33240 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
33250 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
33260 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
33270 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
33280 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
33290 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
332a0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
332b0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
332c0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
332d0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
332e0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
332f0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
33300 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
33310 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
33320 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
33330 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
33340 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
33350 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
33360 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
33370 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  M].)^.*/.SQLITE_
33380 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
33390 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
333a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
333b0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
333c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
333d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
333e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
333f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33400 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33410 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33420 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33430 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33440 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
33450 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33460 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33470 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54  API double SQLIT
33480 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33490 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
334a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
334b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
334c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
334d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
334e0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
334f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33500 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33510 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51  sqlite3_int64 SQ
33520 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
33530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
33540 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
33550 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
33560 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
33570 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49  igned char *SQLI
33580 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
33590 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
335a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
335b0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
335c0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
335d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
335e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
335f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
33600 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
33610 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
33620 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
33630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33650 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33660 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
33670 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  lue *SQLITE_STDC
33680 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
33690 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
336a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
336b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
336c0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
336d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
336e0 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52   Object.** DESTR
336f0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
33700 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
33710 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33720 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
33730 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
33740 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33750 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
33760 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
33770 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
33780 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
33790 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
337a0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
337b0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
337c0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
337d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
337e0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
337f0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
33800 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
33810 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
33820 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
33830 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
33840 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33850 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
33860 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
33870 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
33880 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
33890 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
338a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
338b0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
338c0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
338d0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
338e0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
338f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33900 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
33910 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
33920 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
33930 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
33940 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
33950 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33960 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
33970 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
33980 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
33990 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
339a0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
339b0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
339c0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
339d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
339e0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
339f0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
33a00 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
33a10 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
33a20 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
33a30 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
33a40 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
33a50 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
33a60 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
33a70 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
33a80 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
33a90 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
33aa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
33ab0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
33ac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33ad0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
33ae0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
33af0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
33b00 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
33b10 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
33b20 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
33b30 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
33b40 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
33b50 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33b60 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
33b70 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
33b80 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51  orruption..*/.SQ
33b90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int 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 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
33bc0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
33bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33be0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
33bf0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
33c00 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
33c10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
33c20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33c30 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
33c40 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
33c50 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
33c60 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
33c70 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
33c80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
33c90 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
33ca0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
33cb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
33cc0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
33cd0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
33ce0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
33cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
33d00 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
33d10 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
33d20 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
33d30 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
33d40 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
33d50 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
33d60 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
33d70 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
33d80 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
33d90 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
33da0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33db0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
33dc0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
33dd0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
33de0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
33df0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
33e00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
33e10 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
33e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33e30 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
33e40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
33e50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
33e60 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
33e70 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
33e80 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
33e90 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
33ea0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
33eb0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
33ec0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
33ed0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33ee0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
33ef0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33f00 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
33f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33f20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
33f30 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
33f40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
33f50 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
33f60 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
33f70 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
33f80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33f90 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
33fa0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
33fb0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
33fc0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
33fd0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
33fe0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
33ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
34000 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34010 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
34020 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
34030 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
34040 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34050 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
34060 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
34070 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
34080 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
34090 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
340a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
340b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
340c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
340d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
340e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
340f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
34100 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34110 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
34120 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
34130 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
34140 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
34150 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
34160 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
34170 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
34180 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
34190 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
341a0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
341b0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
341c0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
341d0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
341e0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
341f0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
34200 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
34210 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
34220 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
34230 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
34240 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
34250 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
34260 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
34270 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
34280 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
34290 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
342a0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
342b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
342c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
342d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
342e0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
342f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34300 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
34310 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
34320 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
34330 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
34340 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
34350 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
34360 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
34370 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34380 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
34390 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
343a0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
343b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
343c0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
343d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
343e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
343f0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
34400 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
34410 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
34420 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
34430 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
34440 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
34450 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
34460 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
34470 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
34480 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
34490 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
344a0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
344b0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
344c0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
344d0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
344e0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
344f0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
34500 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
34510 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
34520 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
34530 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
34540 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
34550 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
34560 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
34570 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
34580 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
34590 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
345a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
345b0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
345c0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
345d0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
345e0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
345f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
34600 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
34610 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
34620 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
34630 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
34640 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
34650 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
34660 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
34670 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
34680 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
34690 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
346a0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
346b0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
346c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
346d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
346e0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
346f0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
34700 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
34710 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
34720 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
34730 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
34740 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
34750 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
34760 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
34770 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
34780 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
34790 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
347a0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
347b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
347c0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
347d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
347e0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
347f0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
34800 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
34810 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
34820 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
34830 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34840 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
34850 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
34860 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
34870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34880 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
34890 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
348a0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
348b0 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
348c0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
348d0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
348e0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
348f0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
34900 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
34910 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
34920 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
34930 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
34940 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
34950 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
34960 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
34970 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
34980 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
34990 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
349a0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
349b0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
349c0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
349d0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
349e0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
349f0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
34a00 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
34a10 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
34a20 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
34a30 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
34a40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
34a50 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
34a60 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
34a70 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
34a80 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
34a90 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
34aa0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
34ab0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
34ac0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
34ad0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
34ae0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
34af0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
34b00 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
34b10 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
34b20 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
34b30 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
34b40 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
34b50 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
34b60 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
34b70 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
34b80 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
34b90 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
34ba0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
34bb0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
34bc0 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
34bd0 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
34be0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
34bf0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
34c00 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
34c10 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
34c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
34c30 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
34c40 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
34c50 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
34c60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
34c70 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
34c80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
34c90 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
34ca0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
34cb0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
34cc0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
34cd0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
34ce0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
34cf0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
34d00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34d10 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
34d20 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
34d30 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
34d40 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
34d50 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
34d60 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
34d70 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
34d80 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
34d90 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
34da0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
34db0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
34dc0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
34dd0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
34de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
34df0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
34e00 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
34e10 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
34e20 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
34e30 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
34e40 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
34e50 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
34e60 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
34e70 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
34e80 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
34e90 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
34ea0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
34eb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
34ec0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34ed0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
34ee0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
34ef0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
34f00 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
34f10 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
34f20 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
34f30 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
34f40 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
34f50 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
34f60 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
34f70 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
34f80 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
34f90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
34fa0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
34fb0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
34fc0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
34fd0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
34fe0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34ff0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
35000 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
35010 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
35020 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
35030 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
35040 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
35050 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
35060 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
35070 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
35080 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
35090 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
350a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
350b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
350c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
350d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
350e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
350f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
35100 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
35110 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
35120 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
35130 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
35140 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
35150 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
35160 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
35170 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
35180 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35190 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
351a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
351b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
351c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
351d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
351e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
351f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
35200 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
35210 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35220 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
35230 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
35240 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
35250 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
35260 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
35270 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
35280 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
35290 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
352a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
352b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
352c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
352d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
352e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
352f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
35300 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
35310 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
35320 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
35330 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
35340 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
35350 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
35360 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
35370 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
35380 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
35390 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
353a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
353b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
353c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
353d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
353e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
353f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
35400 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
35410 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35420 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
35430 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
35440 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35450 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
35460 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
35470 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
35480 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
35490 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
354a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
354b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
354c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
354d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
354e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
354f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
35500 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
35510 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
35520 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
35530 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
35540 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
35550 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
35560 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
35570 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
35580 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
35590 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
355a0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
355b0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
355c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
355d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
355e0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
355f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35600 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35610 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
35620 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
35630 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
35640 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
35650 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
35660 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
35670 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35680 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
35690 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
356a0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
356b0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
356c0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
356d0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
356e0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
356f0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35700 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
35710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35720 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35730 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35740 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
35750 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
35760 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
35770 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35780 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35790 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
357a0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
357b0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
357c0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
357d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
357e0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
357f0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
35800 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35810 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35820 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
35830 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
35840 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
35850 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
35860 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
35870 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
35880 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
35890 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
358a0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
358b0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
358c0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
358d0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
358e0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
358f0 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
35900 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
35910 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
35920 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
35930 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
35940 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49         1    /* I
35950 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36  MP: R-37514-3556
35960 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  6 */.#define SQL
35970 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
35980 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20     2    /* IMP: 
35990 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f  R-03371-37637 */
359a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
359b0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
359c0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31      /* IMP: R-51
359d0 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65  971-34154 */.#de
359e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
359f0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
35a00 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
35a10 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
35a20 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
35a30 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
35a40 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a  * Deprecated */.
35a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
35a60 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
35a70 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
35a80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
35a90 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
35aa0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
35ab0 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
35ac0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  se constants may
35ad0 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65   be ORed togethe
35ae0 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  r with the .** [
35af0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72  SQLITE_UTF8 | pr
35b00 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35b10 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f  oding] as the fo
35b20 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
35b30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
35b40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
35b50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35b60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20  _function16()], 
35b70 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
35b80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35b90 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  2()]..*/.#define
35ba0 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e   SQLITE_DETERMIN
35bb0 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a  ISTIC    0x800..
35bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35bd0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
35be0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
35bf0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
35c00 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
35c10 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
35c20 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
35c30 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
35c40 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
35c50 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
35c60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
35c70 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
35c80 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
35c90 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
35ca0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
35cb0 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
35cc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
35cd0 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20  .  To encourage 
35ce0 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61  programmers to a
35cf0 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75  void.** these fu
35d00 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c  nctions, we will
35d10 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61   not explain wha
35d20 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
35d30 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
35d40 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
35d50 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
35d60 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
35d70 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
35d80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35d90 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
35da0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
35db0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
35dc0 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f  ATED int SQLITE_
35dd0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35de0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
35df0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
35e00 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
35e10 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f  ATED int SQLITE_
35e20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35e30 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
35e40 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
35e50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
35e60 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
35e70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
35e80 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
35e90 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
35ea0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
35eb0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
35ec0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
35ed0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
35ee0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
35ef0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
35f00 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
35f10 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
35f20 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
35f30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
35f40 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
35f50 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
35f60 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
35f70 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
35f80 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
35f90 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
35fa0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
35fb0 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ng SQL Values.**
35fc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35fd0 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65  _value.**.** The
35fe0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
35ff0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
36000 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
36010 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
36020 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
36030 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
36040 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
36050 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
36060 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
36070 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
36080 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  .  .**.** The xF
36090 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
360a0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
360b0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
360c0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
360d0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
360e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
360f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
36100 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36110 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
36120 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
36130 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
36140 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36150 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
36160 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36170 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
36180 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
36190 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
361a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
361b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
361c0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
361d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
361e0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
361f0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
36200 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36210 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
36220 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
36230 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
36240 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
36250 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
36270 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
36280 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
36290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
362a0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
362b0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
362c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
362d0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
362e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
362f0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
36300 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
36310 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
36320 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
36330 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
36340 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
36350 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
36360 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
36370 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72  ept that these r
36380 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
36390 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
363a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
363b0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
363c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
363d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
363e0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
363f0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
36400 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
36410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36420 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
36430 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
36440 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
36450 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
36460 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
36470 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
36480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
36490 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
364a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
364b0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
364c0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
364d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
364e0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
364f0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
36500 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
36510 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
36520 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
36530 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
36540 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
36550 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
36560 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
36570 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
36580 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
36590 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
365a0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
365b0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
365c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
365d0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
365e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
365f0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
36600 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
36610 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
36620 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
36630 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
36640 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
36650 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
36660 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
36670 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
36680 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
36690 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
366a0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
366b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
366c0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
366d0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
366e0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
366f0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
36700 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
36710 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
36720 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
36730 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
36740 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
36750 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36760 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
36770 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36780 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
36790 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
367a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
367b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
367c0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
367d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
367e0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
367f0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
36800 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
36810 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
36820 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36830 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
36840 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
36850 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
36860 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
36870 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
36880 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
36890 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
368a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
368b0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
368c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
368d0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
368e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
368f0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
36900 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36910 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
36920 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36930 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
36940 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36950 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
36960 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
36970 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
36980 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43  uble SQLITE_STDC
36990 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
369a0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
369b0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
369c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
369d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
369e0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
369f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36a00 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
36a10 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
36a20 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
36a30 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
36a40 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36a50 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
36a60 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  d char *SQLITE_S
36a70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
36a80 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
36a90 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36aa0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
36ab0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
36ac0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36ad0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
36ae0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36af0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
36b00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36b10 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36b20 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
36b30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
36b40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
36b50 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36b60 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
36b70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
36b80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
36b90 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36ba0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36bb0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
36bc0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
36bd0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
36be0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
36bf0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
36c00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
36c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36c20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
36c30 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
36c40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
36c50 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
36c60 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
36c70 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
36c80 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
36c90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
36ca0 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
36cb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36cc0 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
36cd0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
36ce0 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
36cf0 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
36d00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36d10 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
36d20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
36d30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36d40 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
36d50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36d60 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
36d70 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
36d80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
36d90 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
36da0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36db0 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
36dc0 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
36dd0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36de0 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
36df0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36e00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
36e10 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
36e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
36e30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
36e40 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
36e50 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36e60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  .*/.SQLITE_API S
36e70 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
36e80 41 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  AL sqlite3_value
36e90 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
36ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
36eb0 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  up(const sqlite3
36ec0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36ed0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
36ee0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 53 51  RIMENTAL void SQ
36ef0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36f00 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
36f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36f20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36f30 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
36f40 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
36f50 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ext.** METHOD: s
36f60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
36f70 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
36f80 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
36f90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
36fa0 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
36fb0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
36fc0 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
36fd0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
36fe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
36ff0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
37000 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37010 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
37020 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
37030 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
37040 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
37050 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
37060 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
37070 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
37080 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
37090 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
370a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
370b0 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
370c0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
370d0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
370e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
370f0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
37100 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
37110 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
37120 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
37130 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
37140 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
37150 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37160 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
37170 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
37180 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
37190 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
371a0 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
371b0 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
371c0 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
371d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
371e0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
371f0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
37200 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
37210 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
37220 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
37230 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37240 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
37250 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
37260 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
37270 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
37280 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
37290 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
372a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
372b0 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
372c0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
372d0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
372e0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
372f0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
37300 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37310 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37320 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37330 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
37340 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
37350 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
37360 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
37370 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
37380 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
37390 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
373a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
373b0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
373c0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
373d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
373e0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
373f0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
37400 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
37410 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
37420 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
37430 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
37440 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
37450 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
37460 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37470 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
37480 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
37490 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
374a0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
374b0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
374c0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
374d0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
374e0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
374f0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
37500 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
37510 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
37520 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37530 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
37540 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
37550 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37560 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
37570 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
37580 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
37590 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
375a0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
375b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
375c0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
375d0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
375e0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
375f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
37600 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
37610 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
37620 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
37630 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
37640 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
37650 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
37660 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
37670 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
37680 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
37690 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
376a0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
376b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
376c0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
376d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
376e0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
376f0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
37700 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
37710 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
37720 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
37730 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
37740 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  L sqlite3_aggreg
37750 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
37760 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37770 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
37780 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
37790 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
377a0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
377b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
377c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
377d0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
377e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
377f0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
37800 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
37810 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
37820 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
37830 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
37840 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
37850 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37860 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
37870 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37880 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
37890 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
378a0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
378b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
378c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
378d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
378e0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
378f0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
37900 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
37910 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
37920 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37930 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
37940 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37950 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
37960 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 65  CALL sqlite3_use
37970 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
37980 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
37990 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
379a0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
379b0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
379c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
379d0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
379e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
379f0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
37a00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37a10 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
37a20 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
37a30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37a40 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
37a50 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
37a60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
37a70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
37a80 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
37a90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37aa0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
37ab0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
37ac0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
37ad0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
37ae0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
37af0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
37b00 69 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54 44  ite3 *SQLITE_STD
37b10 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  CALL sqlite3_con
37b20 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
37b30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37b40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37b50 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
37b60 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45  liary Data.** ME
37b70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
37b80 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ntext.**.** Thes
37b90 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
37ba0 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
37bb0 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
37bc0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
37bd0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
37be0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
37bf0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
37c00 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
37c10 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
37c20 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
37c30 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
37c40 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
37c50 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
37c60 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
37c70 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
37c80 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
37c90 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
37ca0 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
37cb0 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
37cc0 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
37cd0 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
37ce0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
37cf0 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
37d00 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
37d10 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
37d20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
37d30 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
37d40 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
37d50 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
37d60 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
37d70 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
37d80 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
37d90 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
37da0 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
37db0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
37dc0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
37dd0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
37de0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
37df0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
37e00 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
37e10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37e20 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
37e30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37e40 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
37e50 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
37e60 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
37e70 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
37e80 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
37e90 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
37ea0 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
37eb0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
37ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37ed0 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
37ee0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
37ef0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
37f00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
37f10 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
37f20 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
37f30 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
37f40 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
37f50 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
37f60 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
37f70 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
37f80 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
37f90 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
37fa0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
37fb0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
37fc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37fd0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
37fe0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
37ff0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
38000 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
38010 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
38020 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
38030 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
38040 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
38050 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
38060 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
38070 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
38080 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
38090 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
380a0 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
380b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
380c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
380d0 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
380e0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
380f0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
38100 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
38110 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
38120 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
38130 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
38140 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
38150 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
38160 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
38170 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
38180 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
38190 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
381a0 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
381b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
381c0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
381d0 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
381e0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
381f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
38200 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
38210 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
38220 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
38230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
38240 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
38250 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
38260 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
38270 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
38280 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
38290 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
382a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
382b0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
382c0 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
382d0 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
382e0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
382f0 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
38300 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
38310 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
38320 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
38330 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
38340 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
38350 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
38360 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
38370 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
38380 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
38390 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
383a0 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
383b0 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
383c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
383d0 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
383e0 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
383f0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
38400 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
38410 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
38420 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
38430 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
38440 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
38450 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
38460 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
38470 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
38480 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
38490 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
384a0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
384b0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
384c0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
384d0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
384e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
384f0 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
38500 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
38510 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
38520 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
38530 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
38540 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
38550 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
38560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
38570 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
38580 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
38590 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
385a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
385b0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
385c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
385d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
385e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
385f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
38600 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  xt*, int N);.SQL
38610 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
38620 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
38630 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38640 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38650 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
38660 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
38670 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
38680 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
38690 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
386a0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
386b0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  or.**.** These a
386c0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
386d0 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  s for the destru
386e0 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
386f0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
38700 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
38710 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
38720 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
38730 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74  _blob()].  ^If t
38740 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
38750 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
38760 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
38770 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
3878