System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 417ee7bb19419ef3ff67d22aa67fbed42011c0c1:


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 32 2e 20 20  ersion 3.8.12.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d  e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72  ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56   options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c  C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20  d be done first 
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76  uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20  ent spurious.** 
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75  s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74  ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68  his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74  er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79   are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f   this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e  nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68  egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72  *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73  s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e  pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56  .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53  C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e  VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72  ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72  able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72  able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72  able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72  able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72  able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72  able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72  able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72  able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72  able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72  able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72  able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72  able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72  able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72  able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e  able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f  dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e  MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20  dif /* _MSVC_H_ 
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e  *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77  *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66  here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   in sqliteInt.h 
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57  al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65  vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a  le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54  15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57  is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f  ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64  ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e  efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56  EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20  xWorks.  Set up 
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79  things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a   for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b  #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70  s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d  thread.h>  /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63  algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ache */.#define 
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65  OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f  fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53  THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f  QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20  RECURSIVE_MUTEX 
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e  _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53  SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43  QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65  KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20  fine HAVE_UTIME 
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20  1.#else./* This 
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20  is not VxWorks. 
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f  WORKS 0.#endif /
11f0: 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b  * defined(_WRS_K
1200: 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a  ERNEL) */../****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f  ********** End o
1220: 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  f vxworks.h ****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69  ********** Conti
1270: 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c  nuing where we l
1280: 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74  eft off in sqlit
1290: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a  *********/../*.*
12b0: 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73  * These #defines
12c0: 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e   should enable >
12d0: 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74  2GB file support
12e0: 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65   on POSIX if the
12f0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  .** underlying o
1300: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1310: 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66  supports it.  If
1320: 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a   the OS lacks.**
1330: 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70   large file supp
1340: 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f  ort, or if the O
1350: 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68  S is windows, th
1360: 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f  ese should be no
1370: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b  -ops..**.** Tick
1380: 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f  et #2739:  The _
1390: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
13a0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65   macro must appe
13b0: 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a  ar before any.**
13c0: 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65   system #include
13d0: 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20  s.  Hence, this 
13e0: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75  block of code mu
13f0: 73 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66  st be the very f
1400: 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20  irst.** code in 
1410: 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73  all source files
1420: 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69  ..**.** Large fi
1430: 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62  le support can b
1440: 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  e disabled using
1450: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49   the -DSQLITE_DI
1460: 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68  SABLE_LFS switch
1470: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  .** on the compi
1480: 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65  ler command line
1490: 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73  .  This is neces
14a0: 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20  sary if you are 
14b0: 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20  compiling.** on 
14c0: 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65  a recent machine
14d0: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e   (ex: Red Hat 7.
14e0: 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20  2) but you want 
14f0: 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72  your code to wor
1500: 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72  k.** on an older
1510: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
1520: 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20  d Hat 6.0).  If 
1530: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52  you compile on R
1540: 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69  ed Hat 7.2.** wi
1550: 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f  thout this optio
1560: 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65  n, LFS is enable
1570: 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20  .  But LFS does 
1580: 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65  not exist in the
1590: 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65   kernel.** in Re
15a0: 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68  d Hat 6.0, so th
15b0: 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72  e code won't wor
15c0: 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d  k.  Hence, for m
15d0: 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a  aximum binary.**
15e0: 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75   portability you
15f0: 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53   should omit LFS
1600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76  ..**.** The prev
1610: 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77  ious paragraph w
1620: 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30  as written in 20
1630: 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67  05.  (This parag
1640: 72 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a  raph is written.
1650: 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38  ** on 2008-11-28
1660: 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61  .) These days, a
1670: 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73  ll Linux kernels
1680: 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66   support large f
1690: 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20  iles, so.** you 
16a0: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20  should probably 
16b0: 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65  leave LFS enable
16c0: 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62  d.  But some emb
16d0: 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20  edded platforms 
16e0: 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46  might.** lack LF
16f0: 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  S in which case 
1700: 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42  the SQLITE_DISAB
1710: 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67  LE_LFS macro mig
1720: 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66  ht still be usef
1730: 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61  ul..**.** Simila
1740: 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61  r is true for Ma
1750: 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20  c OS X.  LFS is 
1760: 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f  only supported o
1770: 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64  n Mac OS X 9 and
1780: 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64   later..*/.#ifnd
1790: 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  ef SQLITE_DISABL
17a0: 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f  E_LFS.# define _
17b0: 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20  LARGE_FILE      
17c0: 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c   1.# ifndef _FIL
17d0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20  E_OFFSET_BITS.# 
17e0: 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f    define _FILE_O
17f0: 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20  FFSET_BITS 64.# 
1800: 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f  endif.# define _
1810: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
1820: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68   1.#endif../* Wh
1830: 61 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43  at version of GC
1840: 43 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e  C is being used.
1850: 20 20 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73    0 means GCC is
1860: 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20   not being used 
1870: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43  */.#ifdef __GNUC
1880: 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f  __.# define GCC_
1890: 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f  VERSION (__GNUC_
18a0: 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43  _*1000000+__GNUC
18b0: 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f  _MINOR__*1000+__
18c0: 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f  GNUC_PATCHLEVEL_
18d0: 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  _).#else.# defin
18e0: 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a  e GCC_VERSION 0.
18f0: 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65  #endif../* Neede
1900: 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65  d for various de
1910: 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a  finitions... */.
1920: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e  #if defined(__GN
1930: 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65  UC__) && !define
1940: 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23  d(_GNU_SOURCE).#
1950: 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55   define _GNU_SOU
1960: 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20  RCE.#endif..#if 
1970: 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53  defined(__OpenBS
1980: 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64  D__) && !defined
1990: 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20  (_BSD_SOURCE).# 
19a0: 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52  define _BSD_SOUR
19b0: 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  CE.#endif../*.**
19c0: 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63   For MinGW, chec
19d0: 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63  k to see if we c
19e0: 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68  an include the h
19f0: 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61  eader file conta
1a00: 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72  ining its.** ver
1a10: 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sion information
1a20: 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  , among other th
1a30: 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c  ings.  Normally,
1a40: 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d   this internal M
1a50: 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66  inGW.** header f
1a60: 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d  ile would [only]
1a70: 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74   be included aut
1a80: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74  omatically by ot
1a90: 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72  her MinGW header
1aa0: 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76  .** files; howev
1ab0: 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  er, the containe
1ac0: 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d  d version inform
1ad0: 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71  ation is now req
1ae0: 75 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  uired by this.**
1af0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20   header file to 
1b00: 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61  work around bina
1b10: 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ry compatibility
1b20: 20 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c   issues (see bel
1b30: 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20  ow) and.** this 
1b40: 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77  is the only know
1b50: 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c  n way to reliabl
1b60: 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68  y obtain it.  Th
1b70: 69 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c  is entire #if bl
1b80: 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20  ock.** would be 
1b90: 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63  completely unnec
1ba0: 65 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20  essary if there 
1bb0: 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61  was any other wa
1bc0: 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a  y of detecting.*
1bd0: 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69  * MinGW via thei
1be0: 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28  r preprocessor (
1bf0: 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73  e.g. if they cus
1c00: 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43  tomized their GC
1c10: 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73  C to define.** s
1c20: 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66  ome MinGW-specif
1c30: 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65  ic macros).  Whe
1c40: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  n compiling for 
1c50: 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68  MinGW, either th
1c60: 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57  e.** _HAVE_MINGW
1c70: 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e  _H or _HAVE__MIN
1c80: 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65  GW_H (note the e
1c90: 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29  xtra underscore)
1ca0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a   macro must be.*
1cb0: 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72  * defined; other
1cc0: 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20  wise, detection 
1cd0: 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70  of conditions sp
1ce0: 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20  ecific to MinGW 
1cf0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62  will be.** disab
1d00: 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  led..*/.#if defi
1d10: 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f  ned(_HAVE_MINGW_
1d20: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69  H).# include "mi
1d30: 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66  ngw.h".#elif def
1d40: 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47  ined(_HAVE__MING
1d50: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22  W_H).# include "
1d60: 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66  _mingw.h".#endif
1d70: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47  ../*.** For MinG
1d80: 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61  W version 4.x (a
1d90: 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63  nd higher), chec
1da0: 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  k to see if the 
1db0: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f  _USE_32BIT_TIME_
1dc0: 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72  T.** define is r
1dd0: 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74  equired to maint
1de0: 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61  ain binary compa
1df0: 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68  tibility with th
1e00: 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a  e MSVC runtime.*
1e10: 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65  * library in use
1e20: 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f   (e.g. for Windo
1e30: 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21  ws XP)..*/.#if !
1e40: 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42  defined(_USE_32B
1e50: 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64  IT_TIME_T) && !d
1e60: 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49  efined(_USE_64BI
1e70: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20  T_TIME_T) && \. 
1e80: 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33     defined(_WIN3
1e90: 32 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  2) && !defined(_
1ea0: 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20  WIN64) && \.    
1eb0: 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f  defined(__MINGW_
1ec0: 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26  MAJOR_VERSION) &
1ed0: 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f  & __MINGW_MAJOR_
1ee0: 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20  VERSION >= 4 && 
1ef0: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f  \.    defined(__
1f00: 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69  MSVCRT__).# defi
1f10: 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49  ne _USE_32BIT_TI
1f20: 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  ME_T.#endif../* 
1f30: 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74  The public SQLit
1f40: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
1f50: 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  e _FILE_OFFSET_B
1f60: 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  ITS macro must a
1f70: 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69  ppear.** first i
1f80: 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68  n QNX.  Also, th
1f90: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
1fa0: 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  E_T macro must a
1fb0: 70 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a  ppear first for.
1fc0: 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a  ** MinGW..*/./**
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63  ************ Inc
1fe0: 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69  lude sqlite3.h i
1ff0: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
2000: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a  ***********/./**
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67  ************ Beg
2030: 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e  in file sqlite3.
2040: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a  ***********/./*.
2070: 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65  ** 2001 Septembe
2080: 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  r 15.**.** The a
2090: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
20a0: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
20b0: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
20c0: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
20d0: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
20e0: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
20f0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
2100: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
2110: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
2120: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
2130: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
2140: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
2150: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
2160: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
2170: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
2180: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
2190: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e0: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64  ***.** This head
21f0: 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20  er file defines 
2200: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68  the interface th
2210: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  at the SQLite li
2220: 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74  brary.** present
2230: 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67  s to client prog
2240: 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75  rams.  If a C-fu
2250: 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72  nction, structur
2260: 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20  e, datatype,.** 
2270: 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  or constant defi
2280: 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  nition does not 
2290: 61 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66  appear in this f
22a0: 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a  ile, then it is.
22b0: 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68  ** not a publish
22c0: 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65  ed API of SQLite
22d0: 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  , is subject to 
22e0: 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a  change without.*
22f0: 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68  * notice, and sh
2300: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65  ould not be refe
2310: 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61  renced by progra
2320: 6d 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ms that use SQLi
2330: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  te..**.** Some o
2340: 66 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  f the definition
2350: 73 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68  s that are in th
2360: 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b  is file are mark
2370: 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69  ed as.** "experi
2380: 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69  mental".  Experi
2390: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
23a0: 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e  s are normally n
23b0: 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72  ew.** features r
23c0: 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f  ecently added to
23d0: 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20   SQLite.  We do 
23e0: 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63  not anticipate c
23f0: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70  hanges.** to exp
2400: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
2410: 61 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65  aces but reserve
2420: 20 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61   the right to ma
2430: 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73  ke minor changes
2440: 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63  .** if experienc
2450: 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74  e from use "in t
2460: 68 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74  he wild" suggest
2470: 20 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72   such changes ar
2480: 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a  e prudent..**.**
2490: 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d   The official C-
24a0: 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63  language API doc
24b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53  umentation for S
24c0: 51 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64  QLite is derived
24d0: 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74  .** from comment
24e0: 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20  s in this file. 
24f0: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68   This file is th
2500: 65 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20  e authoritative 
2510: 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77  source.** on how
2520: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2530: 65 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20  es are supposed 
2540: 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a  to operate..**.*
2550: 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
2560: 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f  is file under co
2570: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
2580: 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74  gement is "sqlit
2590: 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20  e.h.in"..** The 
25a0: 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73  makefile makes s
25b0: 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65  ome minor change
25c0: 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28  s to this file (
25d0: 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e  such as insertin
25e0: 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e  g.** the version
25f0: 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61   number) and cha
2600: 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f  nges its name to
2610: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a   "sqlite3.h" as.
2620: 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  ** part of the b
2630: 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f  uild process..*/
2640: 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45  .#ifndef _SQLITE
2650: 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51  3_H_.#define _SQ
2660: 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64  LITE3_H_.#includ
2670: 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20  e <stdarg.h>    
2680: 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74   /* Needed for t
2690: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66  he definition of
26a0: 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a   va_list */../*.
26b0: 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20  ** Make sure we 
26c0: 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74  can call this st
26d0: 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f  uff from C++..*/
26e0: 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43  .#if 0.extern "C
26f0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
2700: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
2710: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
2720: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
2730: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
2740: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
2750: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
2760: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
2770: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
2780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
2790: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
27a0: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
27b0: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
27c0: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
27d0: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
27e0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
27f0: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
2800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
2810: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
2820: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
2830: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
2840: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
2850: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
2860: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2870: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
2880: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
2890: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
28a0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
28b0: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
28c0: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
28d0: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
28e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
28f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2900: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
2910: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
2920: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
2930: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
2940: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
2950: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
2960: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
2970: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
2980: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
2990: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
29a0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
29b0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
29c0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
29d0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
29e0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
29f0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
2a00: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
2a10: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
2a20: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
2a30: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
2a40: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
2a50: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
2a60: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
2a70: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
2a80: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
2a90: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
2aa0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
2ab0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
2ac0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
2ad0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
2ae0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
2af0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
2b00: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
2b10: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
2b20: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
2b30: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
2b40: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
2b50: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
2b60: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
2b70: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
2b80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
2b90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2ba0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
2bb0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
2bc0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
2bd0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
2be0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
2bf0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
2c00: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
2c10: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
2c20: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
2c30: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
2c40: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c50: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
2c60: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
2c70: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
2c80: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
2c90: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
2ca0: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
2cb0: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
2cc0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
2cd0: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
2ce0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
2cf0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
2d00: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
2d10: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
2d20: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
2d30: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
2d40: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
2d50: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
2d60: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
2d70: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
2d80: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
2d90: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
2da0: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
2db0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
2dc0: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
2dd0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2de0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
2df0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
2e00: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
2e10: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
2e20: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
2e30: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
2e40: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
2e50: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
2e60: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
2e70: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
2e80: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
2e90: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
2ea0: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
2eb0: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
2ec0: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
2ed0: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
2ee0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
2ef0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
2f00: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
2f10: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
2f20: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
2f30: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
2f40: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
2f50: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
2f60: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
2f70: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
2f80: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
2f90: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
2fa0: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
2fb0: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
2fc0: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
2fd0: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
2fe0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
2ff0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
3000: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
3010: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
3020: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
3030: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
3040: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
3050: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
3060: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
3070: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
3080: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
3090: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
30a0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
30b0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
30c0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
30d0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
30e0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
30f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
3100: 20 20 20 20 20 22 33 2e 38 2e 31 32 22 0a 23 64       "3.8.12".#d
3110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
3120: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38  SION_NUMBER 3008
3130: 30 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  012.#define SQLI
3140: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
3150: 20 20 22 32 30 31 35 2d 30 39 2d 31 31 20 31 38    "2015-09-11 18
3160: 3a 30 35 3a 30 31 20 62 66 63 37 62 38 34 62 37  :05:01 bfc7b84b7
3170: 36 36 38 36 30 64 32 65 34 31 30 37 30 32 62 61  66860d2e410702ba
3180: 37 63 31 31 36 36 64 37 33 32 38 33 30 39 61 22  7c1166d7328309a"
3190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31a0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
31b0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
31c0: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
31d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
31e0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
31f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
3200: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
3210: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
3220: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
3230: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
3240: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
3250: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
3260: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3270: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
3280: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
3290: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
32a0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
32b0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
32c0: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
32d0: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
32e0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
32f0: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
3300: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
3310: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
3320: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
3330: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
3340: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
3350: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
3360: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
3370: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69  ader, and thus i
3380: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
3390: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
33a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
33b0: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
33c0: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
33d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
33e0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
33f0: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
3400: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
3410: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
3420: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
3430: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
3440: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
3450: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3460: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
3470: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
3480: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
3490: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
34a0: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
34b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
34c0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34d0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
34e0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
34f0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
3500: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
3510: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
3520: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
3530: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
3540: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
3550: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
3560: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
3570: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
3580: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
3590: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
35a0: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
35b0: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
35c0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
35d0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
35e0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
35f0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
3600: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
3610: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
3620: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
3630: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
3640: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
3650: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
3660: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
3670: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
3680: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
3690: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
36a0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
36b0: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
36c0: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
36d0: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
36e0: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
36f0: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
3700: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
3710: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
3720: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
3730: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
3740: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
3750: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
3760: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
3770: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
3780: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f  sion[] = SQLITE_
3790: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f  VERSION;.SQLITE_
37a0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
37b0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
37c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
37d0: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
37e0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
37f0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3810: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
3820: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
3830: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62  CALL sqlite3_lib
3840: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
3850: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
3860: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
3870: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
3880: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
3890: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
38a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
38b0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
38c0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
38d0: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
38e0: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
38f0: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
3900: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
3910: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
3920: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
3930: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
3940: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
3950: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
3960: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
3970: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
3980: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
3990: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
39a0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
39b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
39c0: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
39d0: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
39e0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
39f0: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
3a00: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
3a10: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
3a20: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
3a30: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
3a40: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
3a50: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
3a60: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3a70: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
3a80: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3a90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
3aa0: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
3ab0: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
3ac0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
3ad0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
3ae0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
3af0: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
3b00: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
3b10: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
3b20: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3b30: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
3b40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3b50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
3b60: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
3b70: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
3b80: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
3b90: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
3ba0: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
3bb0: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
3bc0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
3bd0: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
3be0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
3bf0: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
3c00: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
3c10: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
3c20: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
3c30: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
3c40: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
3c50: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
3c60: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
3c70: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
3c80: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
3c90: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
3ca0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
3cb0: 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f  ptName);.SQLITE_
3cc0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
3cd0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3ce0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
3cf0: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
3d00: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
3d10: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
3d20: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
3d30: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
3d40: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
3d50: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
3d60: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3d70: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
3d80: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
3d90: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
3da0: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65  th mutexing code
3db0: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20   omitted due to 
3dc0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
3dd0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69  HREADSAFE] compi
3de0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62  le-time option b
3df0: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a  eing set to 0..*
3e00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
3e10: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
3e20: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
3e30: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
3e40: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
3e50: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
3e60: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20  ssor macro is 1 
3e70: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
3e80: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
3e90: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
3ea0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
3eb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
3ec0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
3ed0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
3ee0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
3ef0: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
3f00: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
3f10: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
3f20: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
3f30: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
3f40: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
3f50: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
3f60: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
3f70: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
3f80: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
3f90: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
3fa0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
3fb0: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
3fc0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
3fd0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
3fe0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
3ff0: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
4000: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
4010: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  led..** ^The def
4020: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
4030: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20   for mutexes to 
4040: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  be enabled..**.*
4050: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
4060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20   can be used by 
4070: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
4080: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
4090: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
40a0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
40b0: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
40c0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
40d0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
40e0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
40f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
4100: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
4110: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
4120: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
4130: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
4140: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
4150: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
4160: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
4170: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
4180: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
4190: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
41a0: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32  READSAFE=1 or =2
41b0: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72   then mutexes ar
41c0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
41d0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20  ault but.** can 
41e0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74  be fully or part
41f0: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75  ially disabled u
4200: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  sing a call to [
4210: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4220: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65  ].** with the ve
4230: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  rbs [SQLITE_CONF
4240: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
4250: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
4260: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a  _MULTITHREAD],.*
4270: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  * or [SQLITE_CON
4280: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e  FIG_SERIALIZED].
4290: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
42a0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
42b0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
42c0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
42d0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
42e0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
42f0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
4300: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
4310: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
4320: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
4330: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
4340: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
4350: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
4360: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
4370: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
4380: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
4390: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
43a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
43b0: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
43c0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
43d0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
43e0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
43f0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
4400: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
4410: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
4420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
4430: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  afe(void);../*.*
4440: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
4450: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
4460: 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52  Handle.** KEYWOR
4470: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
4480: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
4490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
44a0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
44b0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
44c0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
44d0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
44e0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
44f0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
4500: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
4510: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
4520: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
4530: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
4540: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
4550: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
4560: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
4570: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
4580: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
4590: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
45a0: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
45b0: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
45c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
45d0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
45e0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61  e3_close_v2()] a
45f0: 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  re its destructo
4600: 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  rs.  There are m
4610: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74  any other.** int
4620: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
4630: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
4640: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
4650: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
4660: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
4670: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
4680: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
4690: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
46a0: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
46b0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
46c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
46d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
46e0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
46f0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
4700: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a   Integer Types.*
4710: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
4720: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f  te_int64 sqlite_
4730: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63  uint64.**.** Bec
4740: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f  ause there is no
4750: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20   cross-platform 
4760: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36  way to specify 6
4770: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79  4-bit integer ty
4780: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  pes.** SQLite in
4790: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20  cludes typedefs 
47a0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65  for 64-bit signe
47b0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69  d and unsigned i
47c0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  ntegers..**.** T
47d0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
47e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e   and sqlite3_uin
47f0: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66  t64 are the pref
4800: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e  erred type defin
4810: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73  itions..** The s
4820: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20  qlite_int64 and 
4830: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
4840: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65  pes are supporte
4850: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
4860: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
4870: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
4880: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
4890: 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  and sqlite_int64
48a0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
48b0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a   integer values.
48c0: 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33  ** between -9223
48d0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20  372036854775808 
48e0: 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38  and +92233720368
48f0: 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69  54775807 inclusi
4900: 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ve.  ^The.** sql
4910: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20  ite3_uint64 and 
4920: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
4930: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
4940: 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a  teger values .**
4950: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b   between 0 and +
4960: 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35  1844674407370955
4970: 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a  1615 inclusive..
4980: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
4990: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79  _INT64_TYPE.  ty
49a0: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  pedef SQLITE_INT
49b0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69  64_TYPE sqlite_i
49c0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
49d0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
49e0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
49f0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20  e_uint64;.#elif 
4a00: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
4a10: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42  ) || defined(__B
4a20: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70  ORLANDC__).  typ
4a30: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c  edef __int64 sql
4a40: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
4a50: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f  edef unsigned __
4a60: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
4a70: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70  t64;.#else.  typ
4a80: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  edef long long i
4a90: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  nt sqlite_int64;
4aa0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
4ab0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  ned long long in
4ac0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  t sqlite_uint64;
4ad0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20  .#endif.typedef 
4ae0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
4af0: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65  ite3_int64;.type
4b00: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  def sqlite_uint6
4b10: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4 sqlite3_uint64
4b20: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70  ;../*.** If comp
4b30: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63  iling for a proc
4b40: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73  essor that lacks
4b50: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
4b60: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73  support,.** subs
4b70: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66  titute integer f
4b80: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  or floating-poin
4b90: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
4ba0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
4bb0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
4bc0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
4bd0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
4be0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
4bf0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
4c00: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44   Connection.** D
4c10: 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
4c20: 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
4c30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
4c40: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
4c50: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
4c60: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
4c70: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
4c80: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
4c90: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
4ca0: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
4cb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
4cc0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
4cd0: 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ] if.** the [sql
4ce0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
4cf0: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
4d00: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
4d10: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
4d20: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
4d30: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
4d40: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
4d50: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
4d60: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
4d70: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
4d80: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
4d90: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
4da0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
4db0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
4dc0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
4dd0: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
4de0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4df0: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
4e00: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
4e10: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
4e20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
4e30: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
4e40: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
4e50: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f  tements.** and/o
4e60: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
4e70: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68  ite3_backups, th
4e80: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4e90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d  connection becom
4ea0: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c  es.** an unusabl
4eb0: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68  e "zombie" which
4ec0: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
4ed0: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  lly be deallocat
4ee0: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c  ed when the.** l
4ef0: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ast prepared sta
4f00: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
4f10: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20  zed or the last 
4f20: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69  sqlite3_backup i
4f30: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20  s.** finished.  
4f40: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
4f50: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
4f60: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
4f70: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73   use with.** hos
4f80: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74  t languages that
4f90: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c   are garbage col
4fa0: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72  lected, and wher
4fb0: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77  e the order in w
4fc0: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74  hich.** destruct
4fd0: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69  ors are called i
4fe0: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a  s arbitrary..**.
4ff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
5000: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
5010: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
5020: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
5030: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a  ed statements],.
5040: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
5050: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
5060: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  all [BLOB handle
5070: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  s], and .** [sql
5080: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69  ite3_backup_fini
5090: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c  sh | finish] all
50a0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
50b0: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69  ] objects associ
50c0: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
50d0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
50e0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
50f0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
5100: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a  he object.  ^If.
5110: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ** sqlite3_close
5120: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
5130: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
5140: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
5150: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
5160: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
5170: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
5180: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
5190: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  and/or.** [sqlit
51a0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
51b0: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ts then it retur
51c0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61  ns [SQLITE_OK] a
51d0: 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74  nd the deallocat
51e0: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72  ion.** of resour
51f0: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20  ces is deferred 
5200: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61  until all [prepa
5210: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
5220: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
5230: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
5240: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
5250: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f   are also destro
5260: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  yed..**.** ^If a
5270: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
5280: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ct is destroyed 
5290: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74  while a transact
52a0: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20  ion is open,.** 
52b0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
52c0: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
52d0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
52e0: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65  .** The C parame
52f0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
5300: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73  close(C)] and [s
5310: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
5320: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  C)].** must be e
5330: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
5340: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
5350: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
5360: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
5370: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
5380: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
5390: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
53a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
53b0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74  n_v2()], and not
53c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73   previously clos
53d0: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  ed..** ^Calling 
53e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
53f0: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  or sqlite3_close
5400: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
5410: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67  L pointer.** arg
5420: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c  ument is a harml
5430: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
5440: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
5450: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
5460: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
5470: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
5480: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
5490: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  LL sqlite3_close
54a0: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
54b0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
54c0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
54d0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
54e0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
54f0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
5500: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
5510: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
5520: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
5530: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
5540: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
5550: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
5560: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
5570: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
5580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5590: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
55a0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
55b0: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
55c0: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
55d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
55e0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
55f0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
5600: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
5610: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
5620: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
5630: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
5640: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
5650: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
5660: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
5670: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
5680: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
5690: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
56a0: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
56b0: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
56c0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
56d0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
56e0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
56f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
5700: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
5710: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
5720: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
5730: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
5740: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
5750: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
5760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
5770: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
5780: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
5790: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
57a0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
57b0: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
57c0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
57d0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
57e0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
57f0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
5800: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
5810: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
5820: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
5830: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
5840: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
5850: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
5860: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
5870: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
5880: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
5890: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
58a0: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
58b0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
58c0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
58d0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
58e0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
58f0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
5900: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
5910: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
5920: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
5930: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
5940: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
5950: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
5960: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
5970: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
5980: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
5990: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
59a0: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
59b0: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
59c0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
59d0: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
59e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
59f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
5a00: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
5a10: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
5a20: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
5a30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
5a40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
5a50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
5a60: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
5a70: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
5a80: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
5a90: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
5aa0: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
5ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
5ac0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
5ad0: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
5ae0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
5af0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
5b00: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
5b10: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
5b20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
5b30: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
5b40: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
5b50: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
5b60: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
5b70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
5b80: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
5b90: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
5ba0: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
5bb0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
5bc0: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
5bd0: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
5be0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
5bf0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
5c00: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
5c10: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
5c20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
5c30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
5c40: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
5c50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
5c60: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
5c70: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
5c80: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
5c90: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
5ca0: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
5cb0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
5cc0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
5cd0: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
5ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
5cf0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
5d00: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
5d10: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
5d20: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
5d30: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
5d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
5d50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
5d60: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
5d70: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
5d80: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
5d90: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
5da0: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
5db0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
5dc0: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
5dd0: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
5de0: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
5df0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
5e00: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
5e10: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
5e20: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
5e30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
5e40: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
5e50: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
5e60: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
5e70: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
5e80: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
5e90: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
5ea0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
5eb0: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
5ec0: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
5ed0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
5ee0: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
5ef0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
5f00: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
5f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
5f20: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
5f30: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
5f40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
5f50: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
5f60: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
5f70: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
5f80: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
5f90: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
5fa0: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
5fb0: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
5fc0: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
5fd0: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
5fe0: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
5ff0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
6000: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
6010: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
6020: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
6030: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
6040: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
6050: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
6060: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
6070: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
6080: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
6090: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
60a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
60b0: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
60c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
60d0: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
60e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
60f0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
6100: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
6110: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
6120: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
6130: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
6140: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
6150: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
6160: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
6170: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
6180: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
6190: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
61a0: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
61b0: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
61c0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
61d0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
61e0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
61f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
6200: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
6210: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
6220: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
6250: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
6260: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
6270: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6290: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
62a0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
62b0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
62c0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
62d0: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
62e0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
62f0: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
6320: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
6330: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
6340: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6360: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
6370: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
6380: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
6390: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
63a0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
63b0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
63c0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
63d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
63e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
63f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
6400: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
6410: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
6420: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
6430: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
6440: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
6450: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
6460: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
6470: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
6480: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
6490: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
64a0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
64b0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
64c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64d0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
64e0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
64f0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
6500: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
6510: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
6520: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
6530: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
6540: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
6550: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
6560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
6570: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
6580: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
6590: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
65a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65b0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
65c0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
65d0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
65e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65f0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
6600: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
6610: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
6620: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
6630: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
6640: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
6650: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
6660: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
6670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6680: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
6690: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
66a0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
66b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
66c0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
66d0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
66e0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
66f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
6700: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
6710: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
6720: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
6730: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
6740: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
6750: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
6760: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
6770: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
6780: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
6790: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
67a0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
67b0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
67c0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
67d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67e0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
67f0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
6800: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
6810: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
6820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6830: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
6840: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
6850: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
6860: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
6870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
6880: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
6890: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
68a0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
68b0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
68d0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
68e0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
68f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
6900: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
6910: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
6920: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
6930: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
6940: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
6950: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
6960: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
6970: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
6980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6990: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
69a0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
69b0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
69c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
69d0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
69e0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
69f0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
6a00: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6a20: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
6a30: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
6a40: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
6a50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6a60: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
6a70: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
6a80: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
6a90: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
6aa0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
6ab0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
6ac0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
6ad0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
6ae0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
6af0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
6b00: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
6b10: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
6b20: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
6b30: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
6b40: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
6b50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6b60: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
6b70: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
6b80: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
6b90: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
6ba0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
6bb0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
6bc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
6bd0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
6be0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
6bf0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
6c00: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
6c10: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
6c20: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
6c30: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
6c40: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
6c50: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
6c60: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
6c70: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
6c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6c90: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
6ca0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
6cb0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
6cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
6cd0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
6ce0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
6cf0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
6d00: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
6d20: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
6d30: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
6d40: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
6d50: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
6d60: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
6d70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6d80: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
6d90: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
6da0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
6db0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
6dc0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
6dd0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
6de0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
6df0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
6e00: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
6e10: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
6e20: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
6e30: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
6e40: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
6e50: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
6e60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
6e70: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
6e80: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
6e90: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
6ea0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
6eb0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
6ec0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
6ed0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
6ee0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
6ef0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
6f00: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
6f10: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
6f20: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
6f30: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
6f40: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
6f50: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
6f60: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
6f70: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
6f80: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
6f90: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
6fa0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
6fb0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
6fc0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
6fd0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
6fe0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
6ff0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
7000: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
7010: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
7020: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
7030: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
7040: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
7050: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
7060: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
7070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
7080: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
7090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
70a0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
70c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
70d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
70e0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
70f0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
7100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
7110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7120: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
7130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7140: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
7150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7160: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
7170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7180: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
71b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
71c0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
71e0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
71f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7200: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
7210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7220: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
7230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
7240: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
7250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7260: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
7270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7280: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
7290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
72a0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
72b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
72c0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
72d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
72e0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
72f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7300: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
7310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7320: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
7330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7340: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
7350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7360: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
7370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7380: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
7390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
73a0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
73b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
73c0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
73d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
73e0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
73f0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
7400: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
7410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7420: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
7430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7440: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
7450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7460: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
7470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7480: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
7490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
74a0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
74b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
74c0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
74d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
74e0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
74f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7500: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
7510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7520: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
7530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7540: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
7550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7560: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
7570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7580: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
7590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
75a0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
75b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
75c0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
75d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
75e0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
75f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7600: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
7610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7620: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
7630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7640: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7660: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
7670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7680: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
7690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
76a0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
76b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
76c0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
76d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
76e0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
76f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7700: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
7710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7720: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
7730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7740: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
7750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
7760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
7770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
7780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
7790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
77a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
77b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
77c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
77d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
77e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
77f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
7800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
7810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
7820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
7830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
7840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
7850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
7870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
7890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
78a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
78b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
78c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
78d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
78e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
78f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
7900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
7920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
7930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
7940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
7950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
7970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
7980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
7990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
79a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
79b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
79c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
79d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
79e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
79f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
7a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
7a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
7a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
7a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
7a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
7a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
7aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
7ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
7ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
7b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
7b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
7b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
7b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
7b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
7bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
7bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
7bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
7c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
7c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
7c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
7c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
7ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
7cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
7ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
7d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
7d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
7d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
7d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
7d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
7d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
7db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
7de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
7df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
7e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
7e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
7e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
7e40: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
7e50: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
7e60: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
7e70: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
7e80: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
7e90: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
7ea0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
7eb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
7ec0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
7ed0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
7ee0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
7ef0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
7f00: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7f10: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
7f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f30: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
7f40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
7f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f80: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
7f90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
7fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7fd0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
7fe0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
7ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8020: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8030: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
8040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8060: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
8070: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
8080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80a0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
80b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
80c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
80d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80e0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
80f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
8100: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8110: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8130: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
8140: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
8150: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8160: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8180: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
8190: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
81a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
81b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
81c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
81d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
81e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
81f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8200: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
8210: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
8220: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8240: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
8250: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
8260: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8280: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8290: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
82a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
82b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
82c0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
82d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
82e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
82f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8300: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
8310: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
8320: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8340: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
8350: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
8360: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8370: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8390: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
83a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
83b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
83c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
83d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83e0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
83f0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
8400: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8410: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8430: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
8440: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
8450: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8480: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
8490: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
84a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
84b0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
84c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
84d0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
84e0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
84f0: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
8500: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
8510: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
8520: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
8530: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
8540: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8550: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
8560: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
8570: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
8580: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
8590: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
85a0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
85b0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
85c0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
85d0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
85e0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
85f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8600: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
8610: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
8620: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8630: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8640: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8650: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8660: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8680: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8690: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
86a0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
86b0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
86c0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
86d0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
86e0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
86f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8700: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8710: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8720: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8730: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8740: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8750: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8760: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
8770: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8780: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8790: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
87a0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
87b0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
87c0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
87d0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
87e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
87f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8800: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8810: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8820: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8830: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8840: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8850: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8860: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8870: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
8880: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
8890: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
88a0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
88b0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
88c0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
88d0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
88e0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
88f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
8900: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
8910: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
8920: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
8930: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
8940: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
8950: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
8960: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
8970: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
8980: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8990: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
89a0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
89b0: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
89c0: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
89d0: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
89e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
89f0: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
8a00: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
8a10: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
8a20: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
8a30: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
8a40: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
8a50: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
8a60: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
8a70: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
8a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a90: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
8aa0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
8ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8ac0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
8ad0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8ae0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
8af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8b00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8b10: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
8b20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8b30: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
8b40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
8b50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
8b60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
8b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8b80: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
8b90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8ba0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
8bb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
8bc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8bd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
8be0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8bf0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
8c00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8c10: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
8c20: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
8c30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8c40: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
8c50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8c60: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
8c70: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8c80: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
8c90: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
8ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8cb0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
8cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
8cd0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8ce0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
8cf0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
8d00: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
8d10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
8d20: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8d30: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
8d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d50: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
8d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8d70: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
8d80: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
8d90: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
8da0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
8db0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
8dc0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
8dd0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
8de0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
8df0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
8e00: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
8e10: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
8e20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
8e30: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8e40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8e50: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
8e60: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
8e70: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
8e80: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
8e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8ea0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
8eb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ec0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
8ed0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8ef0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
8f00: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
8f10: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
8f20: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
8f30: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
8f40: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
8f50: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
8f60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8f70: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
8f80: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
8f90: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
8fa0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
8fb0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
8fc0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
8fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
8fe0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
8ff0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
9000: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
9010: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
9020: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
9030: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
9040: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
9050: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
9060: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
9070: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
9080: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
9090: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
90a0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
90b0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
90c0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
90d0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
90e0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
90f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
9100: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
9110: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
9120: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
9130: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
9140: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
9150: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
9160: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
9170: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
9180: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
9190: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
91a0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
91b0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
91c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
91d0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
91e0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
91f0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
9200: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
9210: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
9220: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
9230: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
9240: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
9250: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
9260: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The 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 20  QLITE_SYNC_FULL 
9290: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
92a0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
92b0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
92c0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
92d0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
92e0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
92f0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
9300: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
9310: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
9320: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
9330: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
9340: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
9350: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
9360: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
9370: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
9380: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
9390: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
93a0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
93b0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
93c0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
93d0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
93e0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
93f0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
9400: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
9410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9420: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
9430: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
9440: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
9450: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
9460: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
9470: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
9480: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
9490: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
94a0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
94b0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
94c0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
94d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
94e0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
94f0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
9500: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
9510: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
9520: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
9530: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
9540: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
9550: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
9560: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
9570: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
9580: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
9590: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
95a0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
95b0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
95c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
95d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
95e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
95f0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
9600: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
9610: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
9620: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
9630: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
9640: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
9650: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
9660: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
9670: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
9680: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
9690: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
96a0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
96b0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
96c0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
96d0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
96e0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
96f0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
9700: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
9710: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
9720: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
9730: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
9740: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
9750: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9760: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
9770: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
9780: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
9790: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
97a0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
97b0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
97c0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
97d0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
97e0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
97f0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
9800: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
9810: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
9820: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
9830: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
9840: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9850: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
9860: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
9870: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
9880: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
9890: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
98a0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
98b0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
98c0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
98d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
98e0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
98f0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
9900: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
9910: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
9920: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
9930: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
9940: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
9950: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
9960: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
9970: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
9980: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
9990: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
99a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
99b0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
99c0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
99d0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
99e0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
99f0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
9a00: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
9a10: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
9a20: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
9a30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
9a40: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
9a50: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
9a60: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
9a70: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
9a80: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
9a90: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
9aa0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
9ab0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
9ac0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
9ad0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
9ae0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
9af0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
9b00: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
9b10: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
9b20: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
9b30: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
9b40: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
9b50: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
9b60: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
9b70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9b80: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
9b90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
9ba0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
9bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9bc0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
9bd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9be0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
9bf0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9c00: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
9c10: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
9c20: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9c30: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
9c40: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
9c50: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
9c60: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
9c70: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
9c80: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
9c90: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
9ca0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
9cb0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
9cc0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
9cd0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
9ce0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
9cf0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
9d00: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
9d10: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
9d20: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
9d30: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
9d40: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
9d50: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
9d60: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
9d70: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
9d80: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
9d90: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
9da0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9db0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
9dc0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
9dd0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
9de0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9df0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
9e00: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
9e10: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
9e20: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
9e30: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
9e40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
9e50: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
9e60: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
9e70: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
9e80: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
9e90: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
9ea0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
9eb0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
9ec0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
9ed0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
9ee0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
9ef0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
9f00: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
9f10: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
9f20: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
9f30: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
9f40: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
9f50: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
9f60: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
9f70: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
9f80: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
9f90: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
9fa0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
9fb0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
9fc0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
9fd0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
9fe0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
9ff0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
a000: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
a010: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
a020: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
a030: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
a040: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
a050: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
a060: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
a070: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
a080: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
a090: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
a0a0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
a0b0: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
a0c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
a0d0: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
a0e0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a0f0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
a100: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
a110: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
a120: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
a130: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
a140: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a150: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
a160: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
a170: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
a180: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
a190: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
a1a0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
a1b0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
a1c0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
a1d0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
a1e0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
a1f0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
a200: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a210: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
a220: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
a230: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
a240: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
a250: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
a260: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
a270: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a280: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
a2a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
a2b0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
a2c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a2d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a2e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
a2f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a300: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
a310: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a320: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
a330: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a340: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a350: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
a360: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a370: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
a380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a390: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
a3a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
a3b0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
a3c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
a3d0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
a3e0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
a3f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a400: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
a410: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
a420: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
a430: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
a450: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
a460: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
a470: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
a480: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
a490: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
a4a0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
a4b0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
a4c0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
a4d0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
a4e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a4f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
a500: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
a510: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
a520: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
a530: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
a540: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
a550: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
a560: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
a570: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
a580: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
a590: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
a5a0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
a5b0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
a5c0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a5d0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
a5e0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
a5f0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
a600: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
a610: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
a620: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
a630: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
a640: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
a650: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
a660: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
a670: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
a680: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
a690: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
a6a0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
a6b0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
a6c0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
a6d0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
a6e0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
a6f0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
a700: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
a710: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
a720: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
a730: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
a740: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a750: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
a760: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
a770: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a780: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
a790: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
a7a0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
a7b0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a7c0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
a7d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
a7e0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a7f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a800: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
a810: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a820: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
a830: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
a840: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
a850: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
a860: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
a870: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
a880: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
a890: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
a8a0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
a8b0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
a8c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
a8e0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
a8f0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
a900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
a910: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
a920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a930: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
a940: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
a950: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a960: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
a970: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
a980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a990: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
a9a0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
a9b0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(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 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
a9e0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
a9f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
aa00: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
aa10: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
aa20: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
aa30: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
aa40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
aa50: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
aa60: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
aa70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
aa80: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
aa90: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
aaa0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
aab0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
aac0: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
aad0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
aae0: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
aaf0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
ab00: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
ab10: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
ab20: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
ab30: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
ab40: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
ab50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
ab60: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
ab70: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
ab80: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
ab90: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
aba0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
abb0: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
abc0: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
abd0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
abe0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
abf0: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
ac00: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
ac10: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ac20: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
ac30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ac40: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
ac50: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
ac60: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
ac70: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
ac80: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
ac90: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
aca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
acb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
acc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
acd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
ace0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
acf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
ad00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
ad10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ad20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
ad30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
ad40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
ad50: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
ad60: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
ad70: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ad80: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
ad90: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
ada0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
adb0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
adc0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
add0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
ade0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
adf0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
ae00: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
ae10: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
ae20: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
ae30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
ae40: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
ae50: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
ae60: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
ae70: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
ae80: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
ae90: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
aea0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
aeb0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
aec0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
aed0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
aee0: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
aef0: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
af00: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
af10: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
af20: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
af30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
af40: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
af50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
af60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
af70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
af80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
af90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
afa0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
afb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
afc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
afd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
afe0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
aff0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
b000: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
b010: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
b020: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
b030: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
b040: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
b050: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
b060: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
b070: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
b080: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
b090: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
b0a0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
b0b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
b0c0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
b0d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b0e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b0f0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b110: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
b120: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
b130: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
b140: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
b150: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
b160: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
b170: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
b180: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
b190: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
b1a0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
b1b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b1c0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
b1d0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
b1e0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
b1f0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
b200: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
b210: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
b220: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
b230: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
b240: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
b250: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
b260: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
b270: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
b280: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
b290: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
b2a0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
b2b0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
b2c0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
b2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b2e0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b2f0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b310: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
b320: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
b330: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
b340: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b350: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
b360: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
b370: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
b380: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
b390: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
b3a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b3b0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
b3c0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
b3d0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
b3e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b400: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c  MITTED]].** No l
b410: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a  onger in use..**
b420: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b430: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a  _FCNTL_SYNC]].**
b440: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b450: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20  TL_SYNC] opcode 
b460: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
b470: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
b480: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f  e and.** sent to
b490: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61   the VFS immedia
b4a0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20  tely before the 
b4b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
b4c0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20  invoked on a.** 
b4d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65  database file de
b4e0: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66  scriptor. Or, if
b4f0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b500: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  d is not invoked
b510: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65   .** because the
b520: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67   user has config
b530: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68  ured SQLite with
b540: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e   .** [PRAGMA syn
b550: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
b560: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
b570: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  F] it is invoked
b580: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66   in place .** of
b590: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b5a0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73  d. In most cases
b5b0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72  , the pointer ar
b5c0: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69  gument passed wi
b5d0: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d  th.** this file-
b5e0: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e  control is NULL.
b5f0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
b600: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b610: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a  s being synced.*
b620: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d  * as part of a m
b630: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f  ulti-database co
b640: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65  mmit, the argume
b650: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e  nt points to a n
b660: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
b670: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
b680: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ng the transacti
b690: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e  ons master-journ
b6a0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46  al file name. VF
b6b0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20  Ses that .** do 
b6c0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
b6d0: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65  gnal should sile
b6e0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b6f0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b700: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64  tions .** should
b710: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
b720: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b730: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
b740: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
b750: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20  may .** disrupt 
b760: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
b770: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
b780: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
b790: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
b7a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b7b0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
b7c0: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b  SETWO]].** The [
b7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b7e0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70  MIT_PHASETWO] op
b7f0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
b800: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
b810: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65  SQLite.** and se
b820: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66  nt to the VFS af
b830: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ter a transactio
b840: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69  n has been commi
b850: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  tted immediately
b860: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74  .** but before t
b870: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75  he database is u
b880: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74  nlocked. VFSes t
b890: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  hat do not need 
b8a0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73  this signal.** s
b8b0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
b8c0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
b8d0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
b8e0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a  should not call.
b8f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
b900: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
b910: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
b920: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
b930: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65  rupt the .** ope
b940: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
b950: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
b960: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
b970: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
b980: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b990: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
b9a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b9b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b9c0: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
b9d0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
b9e0: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
b9f0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
ba00: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
ba10: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
ba20: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
ba30: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
ba40: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
ba50: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
ba60: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
ba70: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
ba80: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
ba90: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
baa0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
bab0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
bac0: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
bad0: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
bae0: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
baf0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
bb00: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
bb10: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
bb20: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
bb30: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
bb40: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
bb50: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
bb60: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
bb70: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
bb80: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
bb90: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bba0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
bbb0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
bbc0: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
bbd0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
bbe0: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
bbf0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
bc00: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
bc10: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
bc20: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
bc30: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
bc40: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
bc50: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
bc60: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
bc70: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
bc80: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
bc90: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
bca0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
bcb0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
bcc0: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
bcd0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
bce0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
bcf0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
bd00: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
bd10: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
bd20: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
bd30: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
bd40: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
bd50: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
bd60: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
bd70: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
bd80: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
bd90: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
bda0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
bdb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
bdc0: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
bdd0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bde0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
bdf0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
be00: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
be10: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
be20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
be30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
be40: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
be50: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
be60: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
be70: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
be80: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
be90: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
bea0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
beb0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
bec0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
bed0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
bee0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
bef0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
bf00: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
bf10: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
bf20: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
bf30: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
bf40: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
bf50: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
bf60: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
bf70: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
bf80: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
bf90: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
bfa0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
bfb0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
bfc0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
bfd0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
bfe0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
bff0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
c000: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
c010: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
c020: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
c030: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
c040: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
c050: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
c060: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
c070: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
c080: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
c090: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c0a0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
c0b0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
c0c0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
c0d0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
c0e0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
c0f0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
c100: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
c110: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
c120: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
c130: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c140: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c150: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c160: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c170: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
c180: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
c190: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c1a0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
c1b0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
c1c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c1d0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c1e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
c1f0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
c200: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
c210: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
c220: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
c230: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
c240: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
c250: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
c260: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
c270: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c280: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
c290: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
c2a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
c2b0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
c2c0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
c2d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c2e0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
c2f0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
c300: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c310: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
c320: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
c330: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
c340: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
c350: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
c360: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
c370: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c380: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c390: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c3a0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c3b0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
c3c0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
c3d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c3e0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
c3f0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c400: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
c410: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
c420: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
c430: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
c440: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
c450: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c460: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
c470: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
c480: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
c490: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
c4a0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
c4b0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
c4c0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
c4d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
c4e0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
c4f0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
c500: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c510: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c520: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
c530: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c540: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c550: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c560: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
c570: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
c580: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
c590: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
c5a0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
c5b0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
c5c0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
c5d0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
c5e0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
c5f0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
c600: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
c610: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
c620: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
c630: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
c640: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
c650: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
c660: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c670: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
c680: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
c690: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
c6a0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
c6b0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
c6c0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
c6d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
c6e0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
c6f0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
c700: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
c710: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
c720: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
c730: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
c740: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
c750: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
c760: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
c770: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
c780: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
c790: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
c7a0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
c7b0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
c7c0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
c7d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c7e0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
c7f0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
c800: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
c810: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
c820: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c830: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
c840: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
c850: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
c860: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
c870: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
c880: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
c890: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
c8a0: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
c8b0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
c8c0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
c8d0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [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 69 73 20 61 6e 20 61   control is an a
c900: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
c910: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
c920: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
c930: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
c940: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
c950: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
c960: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
c970: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
c980: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
c990: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
c9a0: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
c9b0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
c9c0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
c9d0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
c9e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c9f0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ca00: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
ca10: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
ca20: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
ca30: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
ca40: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
ca50: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
ca60: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ca70: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
ca80: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
ca90: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
caa0: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
cab0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
cac0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
cad0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
cae0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
caf0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
cb00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cb10: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
cb20: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
cb30: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
cb40: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
cb50: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
cb60: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
cb70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb80: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
cb90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
cba0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
cbb0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
cbc0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
cbd0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
cbe0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
cbf0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
cc00: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
cc10: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
cc20: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
cc30: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
cc40: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
cc50: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
cc60: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
cc70: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
cc80: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
cc90: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ccb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ccc0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
ccd0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
cce0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
ccf0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
cd00: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
cd10: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
cd20: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
cd30: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
cd40: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
cd50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
cd60: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
cd70: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
cd80: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
cd90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
cda0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
cdb0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
cdc0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
cdd0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
cde0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
cdf0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
ce00: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
ce10: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
ce20: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
ce30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ce40: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ce50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ce60: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
ce70: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
ce80: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
ce90: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
cea0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
ceb0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
cec0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
ced0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
cee0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
cef0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
cf00: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
cf10: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
cf20: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
cf30: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
cf40: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
cf50: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
cf60: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
cf70: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
cf80: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
cf90: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
cfa0: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
cfb0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
cfc0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
cfd0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
cfe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
cff0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
d000: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
d010: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
d020: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
d030: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
d040: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
d050: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
d060: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
d070: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
d080: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
d090: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
d0a0: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
d0b0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
d0c0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
d0d0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
d0e0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
d0f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
d110: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
d120: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
d130: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
d140: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
d150: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
d160: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
d170: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
d180: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
d190: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
d1a0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
d1b0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
d1c0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
d1d0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
d1e0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
d1f0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
d200: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
d210: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
d220: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
d230: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
d240: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
d250: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
d260: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
d270: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
d280: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
d290: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
d2a0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
d2b0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
d2c0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
d2d0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
d2e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d2f0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
d300: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d310: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
d320: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
d330: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
d340: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
d350: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
d360: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
d370: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
d380: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
d390: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
d3a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
d3b0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
d3c0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
d3d0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
d3e0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
d3f0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
d400: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
d410: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
d420: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
d430: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
d440: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
d450: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
d460: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
d470: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
d480: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
d490: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
d4a0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
d4b0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
d4c0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
d4d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
d4e0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
d4f0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
d500: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
d510: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
d520: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
d530: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
d540: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d550: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
d560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
d570: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
d580: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
d590: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
d5a0: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
d5b0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
d5c0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
d5d0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
d5e0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
d5f0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d600: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
d610: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
d620: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
d630: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
d640: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
d650: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
d660: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
d670: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
d680: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
d690: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
d6a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
d6b0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
d6c0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
d6d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d6e0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
d6f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d700: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
d710: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
d720: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
d730: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
d740: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
d750: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
d760: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
d770: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
d780: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
d790: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
d7a0: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
d7b0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
d7c0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
d7d0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
d7e0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
d7f0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
d800: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
d810: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d820: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
d830: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
d840: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d850: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
d860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
d870: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
d880: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
d890: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
d8a0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
d8b0: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
d8c0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
d8d0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
d8e0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
d8f0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
d900: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
d910: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
d920: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
d930: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
d940: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
d950: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
d960: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d970: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
d980: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d990: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
d9a0: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
d9b0: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
d9c0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
d9d0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
d9e0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
d9f0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
da00: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
da10: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
da20: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
da30: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
da40: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
da50: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
da60: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
da70: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
da80: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
da90: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
daa0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
dab0: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
dac0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
dad0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
dae0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
daf0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
db00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
db10: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
db20: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
db30: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
db40: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
db50: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
db60: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
db70: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
db80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
db90: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
dba0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
dbb0: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
dbc0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
dbd0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
dbe0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
dbf0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
dc00: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
dc10: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
dc20: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
dc30: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
dc40: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ode.  .** </ul>.
dc50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dc60: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
dc70: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
dc80: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
dc90: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dca0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
dcb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcc0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
dcd0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
dce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dcf0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
dd00: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
dd10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dd20: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
dd40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dd50: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
dd60: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
dd70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dd80: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
dd90: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ddb0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
ddc0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
ddd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dde0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
ddf0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
de00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
de10: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
de20: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
de30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
de40: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
de50: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
de60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
de70: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
de80: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
de90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
dea0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
deb0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
dec0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ded0: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
dee0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
def0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
df00: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
df10: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
df20: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
df30: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
df40: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
df50: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
df60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
df70: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
df80: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
df90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
dfa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dfb0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
dfc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
dfd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dfe0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
dff0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
e000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e010: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
e020: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
e030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e040: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
e050: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
e060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e070: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
e080: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
e090: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e0a0: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
e0b0: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
e0c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e0d0: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
e0e0: 20 20 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65         26../* de
e0f0: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
e100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e110: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
e120: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
e130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
e140: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
e150: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
e160: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
e170: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
e180: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
e190: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
e1a0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
e1b0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
e1c0: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
e1d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
e1e0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
e1f0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
e200: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
e210: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
e220: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
e230: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
e240: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
e250: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
e260: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
e270: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
e280: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
e290: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
e2a0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
e2b0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
e2c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
e2d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
e2e0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
e2f0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
e300: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
e310: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
e320: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e330: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
e340: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
e350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e360: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
e370: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
e380: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
e390: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e3a0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
e3b0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
e3c0: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
e3d0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
e3e0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
e3f0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
e400: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
e410: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
e420: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
e430: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
e440: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
e450: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
e460: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
e470: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
e480: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
e490: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
e4a0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
e4b0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
e4c0: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
e4d0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
e4e0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
e4f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
e500: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
e510: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
e520: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
e530: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
e540: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
e550: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
e560: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
e570: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
e580: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
e590: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
e5a0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
e5b0: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
e5c0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
e5d0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
e5e0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
e5f0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
e600: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
e610: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
e620: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
e630: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
e640: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
e650: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
e660: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
e670: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
e680: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
e690: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
e6a0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
e6b0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
e6c0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
e6d0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
e6e0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
e6f0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
e700: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
e710: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
e720: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
e730: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
e740: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
e750: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
e760: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
e770: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
e780: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
e790: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
e7a0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
e7b0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
e7c0: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
e7d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
e7e0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
e7f0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
e800: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
e810: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
e820: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
e830: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
e840: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
e850: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
e860: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
e870: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
e880: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
e890: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
e8a0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
e8b0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
e8c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
e8d0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
e8e0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
e8f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
e900: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
e910: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
e920: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
e930: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
e940: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
e950: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
e960: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
e970: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
e980: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
e990: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
e9a0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
e9b0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e9c0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e9d0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e9f0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
ea00: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
ea10: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
ea20: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
ea30: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
ea40: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
ea50: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
ea60: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
ea70: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
ea80: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ea90: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
eaa0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
eab0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
eac0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
ead0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
eae0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
eaf0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
eb00: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
eb10: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
eb20: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
eb30: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
eb40: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
eb50: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
eb60: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
eb70: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
eb80: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
eb90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
eba0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ebb0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ebc0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ebd0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ebe0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ebf0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ec00: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ec10: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ec20: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ec30: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ec40: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
ec50: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
ec60: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ec70: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
ec80: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
ec90: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
eca0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
ecb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
ecc0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
ecd0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
ece0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
ecf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ed00: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
ed10: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
ed20: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
ed30: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
ed40: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
ed50: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ed60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
ed70: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ed80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ed90: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
eda0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
edb0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
edc0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
edd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
ede0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
edf0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
ee00: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
ee10: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
ee20: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
ee30: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
ee40: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
ee50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
ee60: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
ee70: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
ee80: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
ee90: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
eea0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
eeb0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
eec0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
eed0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
eee0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
eef0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
ef00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
ef10: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ef20: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
ef30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ef40: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
ef50: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ef60: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
ef70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ef80: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
ef90: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
efa0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
efb0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
efc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
efd0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
efe0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
eff0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
f000: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
f010: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
f020: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
f030: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
f040: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
f050: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
f060: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
f070: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
f080: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
f090: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
f0a0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
f0b0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
f0c0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
f0d0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
f0e0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
f0f0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
f100: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
f110: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
f120: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
f130: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
f140: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
f150: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
f160: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
f170: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
f180: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
f190: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
f1a0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
f1b0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
f1c0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
f1d0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
f1e0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
f1f0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
f200: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
f210: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
f220: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
f230: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
f240: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
f250: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
f260: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
f270: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
f280: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
f290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
f2a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f2b0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
f2c0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2d0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
f2e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
f2f0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f300: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
f310: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f320: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
f330: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
f340: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
f350: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f360: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
f370: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
f380: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
f390: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
f3a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
f3b0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
f3c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
f3d0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f3e0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
f3f0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
f400: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
f410: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
f420: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
f430: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
f440: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
f450: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
f460: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
f470: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
f480: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
f490: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
f4a0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
f4b0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
f4c0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
f4d0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
f4e0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f4f0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
f500: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
f510: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
f520: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
f530: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
f540: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
f550: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
f560: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
f570: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
f580: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
f590: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
f5a0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
f5b0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
f5c0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
f5d0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
f5e0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
f5f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
f600: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
f610: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
f620: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f630: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
f640: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
f650: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
f660: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
f670: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
f680: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
f690: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
f6a0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
f6b0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
f6c0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
f6d0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
f6e0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
f6f0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
f700: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
f710: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
f720: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
f730: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
f740: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
f750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f760: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
f770: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
f780: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
f790: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
f7a0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
f7b0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
f7c0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
f7d0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f7e0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
f7f0: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
f800: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
f810: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
f820: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
f830: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
f840: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
f850: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
f860: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f870: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
f880: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f890: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
f8a0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
f8b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
f8c0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
f8d0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
f8e0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
f8f0: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
f900: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
f910: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
f920: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
f930: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
f940: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
f950: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
f960: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
f970: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
f980: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
f990: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f9a0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
f9b0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f9c0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f9d0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f9e0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f9f0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
fa00: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
fa10: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
fa20: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
fa30: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
fa40: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
fa50: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
fa60: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
fa70: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
fa80: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
fa90: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
faa0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
fab0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
fac0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
fad0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
fae0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
faf0: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
fb00: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
fb10: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
fb20: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
fb30: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
fb40: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
fb50: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
fb60: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
fb70: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
fb80: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
fb90: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
fba0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
fbb0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
fbc0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
fbd0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
fbe0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
fbf0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
fc00: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
fc10: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
fc20: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
fc30: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
fc40: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
fc50: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
fc60: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
fc70: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
fc80: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
fc90: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
fca0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
fcb0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
fcc0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
fcd0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
fce0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
fcf0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
fd00: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
fd10: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
fd20: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
fd30: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fd40: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
fd50: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
fd60: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
fd70: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
fd80: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
fd90: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
fda0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
fdb0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
fdc0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
fdd0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
fde0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fdf0: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
fe00: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
fe10: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
fe20: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
fe30: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
fe40: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
fe50: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
fe60: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fe70: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
fe80: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
fe90: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
fea0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
feb0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
fec0: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
fed0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
fee0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
fef0: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
ff00: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
ff10: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
ff20: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
ff30: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
ff40: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
ff50: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
ff60: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
ff70: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
ff80: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
ff90: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
ffa0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
ffb0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
ffc0: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
ffd0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
ffe0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
fff0: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
10000 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
10010 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
10020 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
10030 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
10040 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
10050 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
10060 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
10070 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
10080 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
10090 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
100a0 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
100b0 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
100c0 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
100d0 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
100e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
100f0 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
10100 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
10110 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
10120 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
10130 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
10140 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
10150 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
10160 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
10170 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
10180 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
10190 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
101a0 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
101b0 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
101c0 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
101d0 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
101e0 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
101f0 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
10200 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
10210 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
10220 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
10230 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
10240 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
10250 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
10260 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
10270 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
10280 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
10290 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
102a0 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
102b0 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
102c0 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
102d0 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
102e0 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
102f0 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
10300 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
10310 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
10320 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
10330 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
10340 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
10350 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
10360 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
10370 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
10380 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
10390 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
103a0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
103b0 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
103c0 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
103d0 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
103e0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
103f0 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
10400 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10410 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
10420 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
10430 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
10440 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
10450 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
10460 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10470 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10480 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
10490 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
104a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
104b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
104c0 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
104d0 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
104e0 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
104f0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10500 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10510 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
10520 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
10530 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
10540 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10550 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
10560 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
10570 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
10580 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10590 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
105a0 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
105b0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
105c0 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
105d0 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
105e0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
105f0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
10600 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
10610 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
10620 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
10630 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
10640 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
10650 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
10660 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
10670 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
10680 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
10690 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
106a0 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
106b0 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
106c0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
106d0 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
106e0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
106f0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
10700 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
10710 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
10720 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
10730 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
10740 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
10750 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
10760 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
10770 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
10780 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10790 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
107a0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
107b0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
107c0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
107d0 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
107e0 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
107f0 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
10800 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
10810 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
10820 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
10830 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10840 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10850 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
10860 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10870 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
10880 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
10890 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
108a0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
108b0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
108c0 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
108d0 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
108e0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
108f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
10900 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10910 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
10920 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
10930 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
10940 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
10950 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
10960 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
10970 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
10980 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
10990 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
109a0 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
109b0 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
109c0 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
109d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
109e0 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
109f0 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
10a00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
10a10 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
10a20 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
10a30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
10a40 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
10a50 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
10a60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
10a70 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
10a80 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
10a90 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
10aa0 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
10ab0 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10ac0 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10ad0 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10ae0 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10af0 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10b00 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10b10 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10b20 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10b30 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
10b40 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b50 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10b60 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
10b70 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
10b80 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
10b90 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
10ba0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
10bb0 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10bc0 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10bd0 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10be0 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10bf0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10c00 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10c10 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10c20 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10c30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10c40 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10c50 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
10c60 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
10c70 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10c80 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
10c90 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
10ca0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
10cb0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10cc0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10cd0 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10ce0 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10cf0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10d00 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10d10 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10d20 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10d30 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10d40 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10d50 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
10d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10d70 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10d80 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
10d90 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10da0 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
10db0 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10dc0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10de0 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10df0 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10e00 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10e10 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10e20 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10e30 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10e40 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10e50 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10e60 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10e70 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10e80 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
10e90 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
10ea0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
10eb0 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10ec0 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10ed0 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10ee0 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10ef0 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10f00 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10f10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10f20 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10f30 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10f40 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10f50 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10f60 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10f70 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10f80 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10f90 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10fa0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10fb0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10fc0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10fd0 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10fe0 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10ff0 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
11000 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
11010 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
11020 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
11030 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
11040 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
11050 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
11060 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
11070 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
11080 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
11090 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
110a0 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
110b0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
110c0 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
110d0 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
110e0 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
110f0 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
11100 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
11110 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
11120 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
11130 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
11140 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
11150 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
11160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11170 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
11180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11190 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
111a0 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
111b0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
111c0 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
111d0 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
111e0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
111f0 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
11200 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
11210 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
11220 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
11230 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
11240 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
11250 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
11260 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
11270 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
11280 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11290 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
112a0 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
112b0 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
112c0 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
112d0 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
112e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
112f0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
11300 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
11310 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11320 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
11330 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
11340 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
11350 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
11360 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
11370 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
11380 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
11390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
113a0 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
113b0 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
113c0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
113d0 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
113e0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
113f0 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
11400 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
11410 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
11420 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
11430 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
11440 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
11450 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
11460 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11470 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
11480 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
11490 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
114a0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
114b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
114c0 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
114d0 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
114e0 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
114f0 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
11500 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
11510 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11520 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
11530 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
11540 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
11550 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
11560 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
11570 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
11580 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
11590 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
115a0 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
115b0 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
115c0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
115d0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
115e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
115f0 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
11600 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
11610 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
11620 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11630 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
11640 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
11650 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
11660 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
11670 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
11680 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11690 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
116a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
116b0 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
116c0 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
116d0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
116e0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
116f0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
11700 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11710 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
11720 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
11730 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11740 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
11750 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
11760 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
11770 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
11780 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
11790 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
117a0 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
117b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
117c0 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
117d0 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
117e0 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
117f0 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
11800 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
11810 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
11820 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
11830 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
11840 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
11850 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
11860 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
11870 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
11880 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
11890 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
118a0 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
118b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
118c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
118d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
118e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
118f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11900 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
11910 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
11920 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11930 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
11940 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
11950 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
11960 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
11970 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
11980 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
11990 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
119a0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
119b0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
119c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
119d0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
119e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
119f0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11a00 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
11a10 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
11a20 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
11a30 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
11a40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
11a50 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
11a60 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
11a70 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11a80 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
11a90 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
11aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
11ab0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11ac0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11ad0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11ae0 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11af0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11b00 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11b10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11b20 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11b30 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
11b40 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
11b50 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
11b60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11b70 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
11b80 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11b90 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
11ba0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
11bb0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11bc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11bd0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11be0 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11bf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11c00 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11c10 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11c20 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11c30 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11c40 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11c50 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
11c60 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
11c70 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11c80 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
11c90 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
11ca0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11cb0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11cc0 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11cd0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11ce0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11cf0 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11d00 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11d10 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11d20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11d30 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11d40 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11d50 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11d60 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
11d70 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11d80 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
11d90 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
11da0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
11db0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11dc0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11dd0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11de0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11df0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11e00 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11e10 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11e20 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11e30 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11e40 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11e50 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11e60 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11e70 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11e80 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
11e90 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
11ea0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
11eb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11ec0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11ed0 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11ee0 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11ef0 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11f00 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11f10 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11f20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11f30 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11f40 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11f60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11f70 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11f90 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
11fa0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
11fb0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11fc0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11fd0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11ff0 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
12000 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
12010 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
12020 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
12030 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
12050 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
12060 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
12070 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12080 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
12090 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
120a0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
120b0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
120c0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
120d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
120e0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
120f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
12100 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
12110 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
12120 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
12130 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
12140 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
12150 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
12160 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
12170 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
12180 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
12190 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
121a0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
121b0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
121c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
121d0 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
121e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
121f0 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
12200 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
12210 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
12220 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
12230 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
12240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12250 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
12260 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
12270 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
12280 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
12290 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
122a0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
122b0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
122c0 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51  * failure..*/.SQ
122d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
122e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
122f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
12300 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
12310 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
12320 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ALL sqlite3_shut
12330 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
12340 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12350 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
12360 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
12370 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12380 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
12390 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
123a0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
123b0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
123c0 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
123d0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
123e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
123f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
12400 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
12410 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
12420 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
12430 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
12440 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
12450 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
12460 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
12470 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
12480 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
12490 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
124a0 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
124b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
124c0 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
124d0 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
124e0 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
124f0 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
12500 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
12510 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
12520 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
12530 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12540 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12550 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
12560 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
12570 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
12580 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
12590 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
125a0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
125b0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
125c0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
125d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
125e0 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
125f0 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
12600 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
12610 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
12620 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
12630 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
12640 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
12650 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
12660 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
12670 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
12680 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
12690 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
126a0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
126b0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
126c0 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
126d0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
126e0 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
126f0 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
12700 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
12710 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
12720 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
12730 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
12740 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
12750 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
12760 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
12770 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
12780 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
12790 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
127a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
127b0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
127c0 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
127d0 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
127e0 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
127f0 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
12800 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
12810 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
12820 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
12830 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12840 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
12850 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
12860 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
12870 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
12880 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
12890 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
128a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
128b0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
128c0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
128d0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
128e0 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
128f0 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
12900 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
12910 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
12920 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
12930 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
12940 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
12950 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
12960 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44  PI int SQLITE_CD
12970 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ECL sqlite3_conf
12980 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
12990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
129a0 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
129b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
129c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
129d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
129e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
129f0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
12a00 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
12a10 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
12a20 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
12a30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
12a40 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
12a50 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
12a60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12a70 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
12a80 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
12a90 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
12aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12ab0 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
12ac0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
12ad0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
12ae0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12af0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
12b00 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
12b10 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
12b20 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12b30 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
12b40 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
12b50 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
12b60 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
12b70 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
12b80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
12b90 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
12ba0 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
12bb0 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
12bc0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
12bd0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
12be0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
12bf0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
12c00 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12c10 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
12c20 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
12c30 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
12c40 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
12c50 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
12c60 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
12c70 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
12c80 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
12c90 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
12ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
12cc0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
12cd0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
12ce0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12cf0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
12d00 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
12d10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
12d20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12d30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
12d50 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
12d60 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
12d70 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
12d80 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
12d90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12da0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12db0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
12dc0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
12dd0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
12de0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12df0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12e10 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12e30 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
12e40 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
12e50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
12e60 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
12e70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12e80 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
12e90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
12ea0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
12eb0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
12ec0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
12ed0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12ef0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
12f00 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
12f10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
12f20 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
12f30 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
12f40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
12f50 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
12f60 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
12f70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
12f80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
12f90 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
12fa0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
12fb0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12fd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
12fe0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
12ff0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
13000 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
13010 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
13020 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
13030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13040 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
13050 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
13060 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
13070 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
13080 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
13090 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
130a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
130b0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
130c0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
130d0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
130e0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
130f0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
13100 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
13110 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
13120 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
13130 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13140 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
13150 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
13160 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
13170 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
13180 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13190 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
131a0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
131b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
131c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
131d0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
131e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
131f0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
13200 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
13210 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
13220 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
13230 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
13240 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
13250 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
13260 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
13280 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
13290 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
132a0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
132b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
132c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
132d0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
132e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
132f0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
13300 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
13310 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
13320 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
13330 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
13340 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
13350 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13360 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
13370 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
13380 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
13390 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
133a0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
133c0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
133d0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
133e0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
133f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
13400 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
13410 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
13420 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
13430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13440 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
13450 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
13460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
13470 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
13480 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
13490 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
134a0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
134b0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
134c0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
134d0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
134e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
134f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
13500 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
13510 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
13520 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
13530 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
13540 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
13550 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
13560 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
13570 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
13580 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
13590 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
135a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
135b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
135d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
135e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
135f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
13600 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
13610 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
13620 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
13630 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
13640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
13650 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
13660 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
13670 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
13680 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
13690 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
136a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
136b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
136c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
136d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
136e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
136f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
13700 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
13710 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
13720 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
13730 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
13740 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
13750 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
13760 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
13770 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
13780 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
13790 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
137a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
137b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
137d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
137e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
137f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
13800 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
13810 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
13820 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
13830 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
13840 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
13850 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
13860 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
13870 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
13880 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
13890 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
138a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
138b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
138c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
138d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
138e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
138f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
13900 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
13910 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
13920 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
13930 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
13940 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
13950 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
13960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
13970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13980 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
13990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
139a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
139b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
139c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
139d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
139e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
139f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
13a00 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
13a10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
13a20 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
13a30 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
13a40 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
13a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
13a60 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
13a70 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
13a80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
13a90 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
13aa0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
13ab0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
13ac0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
13ad0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
13ae0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
13af0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
13b00 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
13b10 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
13b20 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
13b30 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
13b40 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
13b50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
13b60 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
13b70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b80 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
13b90 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
13ba0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
13bb0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
13bc0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
13bd0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
13be0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
13bf0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
13c00 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
13c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
13c20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
13c30 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
13c40 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
13c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c60 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13c70 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13cb0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
13cc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13cd0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
13ce0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
13cf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
13d00 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
13d10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d20 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
13d30 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
13d40 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
13d50 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
13d60 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
13d70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
13d80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
13d90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
13da0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
13db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13dc0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13dd0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
13de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
13df0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
13e00 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
13e10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13e20 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
13e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13e50 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
13e60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
13e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13e90 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13ea0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13eb0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13ec0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13ed0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13ee0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
13ef0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13f00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
13f10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
13f20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
13f30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
13f40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
13f50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
13f60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
13f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13f80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13f90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13fa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13fb0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13fc0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13fd0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13fe0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
13ff0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
14000 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
14010 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
14020 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
14030 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
14040 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14050 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
14060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14070 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14090 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
140a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
140b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140d0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140f0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
14100 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14110 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14120 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14130 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14140 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14150 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
14160 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
14170 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
14180 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
14190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
141a0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
141b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
141c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
141d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
141e0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
141f0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
14200 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
14220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14230 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
14240 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
14250 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
14260 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14270 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
14280 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
14290 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
142a0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
142b0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
142c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
142d0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
142e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
142f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14300 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
14310 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14320 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14330 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14360 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14370 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14380 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
14390 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
143a0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
143b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
143c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
143d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
143e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
143f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14400 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
14410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14440 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
14450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
14460 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
14470 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
14480 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
14490 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
144a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
144b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
144c0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
144d0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
144e0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
144f0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
14500 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
14510 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
14520 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14550 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14560 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
14570 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
14580 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
14590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
145a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
145b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
145c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
145d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
145e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
145f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
14600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
14610 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
14620 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
14630 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
14640 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
14650 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
14660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14670 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
14680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14690 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
146a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
146b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
146c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
146d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
146e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
146f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14700 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14720 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
14730 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
14740 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
14750 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
14760 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
14770 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
14790 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
147a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
147c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
147e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
14800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14810 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
14820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14840 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14850 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14860 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
14870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14880 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14890 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
148a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
148b0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
148c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
148d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
148e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
148f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
14900 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
14910 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
14920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
14930 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14940 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
14950 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
14960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
14970 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
14980 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14990 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
149a0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
149b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
149c0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
149d0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
149e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
149f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
14a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14a10 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
14a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
14a40 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14a50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14a60 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14a80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14aa0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14ab0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
14ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
14ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
14ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
14af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
14b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
14b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
14bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
14bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
14bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14bf0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
14c00 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14c10 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
14c20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14c30 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
14c40 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
14c50 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
14c60 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
14c70 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14c80 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14c90 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14ca0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14cb0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14cc0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14cd0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
14ce0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14cf0 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
14d00 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
14d10 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
14d20 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
14d30 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
14d40 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
14d50 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14d60 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14d70 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14d80 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14d90 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14da0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14db0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14dc0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
14dd0 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
14de0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
14df0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14e00 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
14e10 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
14e20 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
14e30 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
14e40 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
14e50 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
14e60 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
14e70 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
14e80 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
14e90 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
14ea0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
14eb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14ec0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
14ed0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14ee0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
14ef0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14f00 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14f10 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
14f20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
14f30 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
14f40 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
14f50 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
14f60 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
14f70 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
14f80 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
14f90 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
14fa0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
14fb0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
14fc0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
14fd0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
14fe0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
14ff0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
15000 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
15010 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
15020 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
15030 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
15040 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
15050 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
15060 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15070 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
15080 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15090 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
150a0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
150b0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
150c0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
150d0 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
150e0 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
150f0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
15100 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
15110 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
15120 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
15130 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
15140 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
15150 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
15160 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
15170 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
15180 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
15190 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
151a0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
151b0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
151c0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
151d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
151e0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
151f0 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
15200 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
15210 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
15220 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
15230 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
15240 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
15250 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
15260 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
15270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
15280 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
15290 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
152a0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
152b0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
152c0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
152d0 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
152e0 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
152f0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15300 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
15310 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
15320 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
15330 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
15340 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
15350 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15360 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15370 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
15380 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15390 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
153a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
153b0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
153c0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
153d0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
153e0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
153f0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
15400 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
15410 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
15420 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
15430 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15440 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
15450 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
15460 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15470 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
15480 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
15490 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
154a0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
154b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
154c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
154d0 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  2].** configurat
154e0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e  ion option..** ^
154f0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15500 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15510 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15520 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
15530 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
15540 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
15550 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
15560 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
15570 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
15580 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
15590 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
155a0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
155b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
155c0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
155d0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
155e0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
155f0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
15600 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
15610 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
15620 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
15630 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15640 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
15650 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
15660 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
15670 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
15680 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15690 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70  PCACHE_HDRSZ] op
156a0 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tion .** to [sql
156b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
156c0 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  ** ^It is harmle
156d0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
156e0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
156f0 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20  ,.** for the sz 
15700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
15710 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65  larger than nece
15720 73 73 61 72 79 2e 20 20 54 68 65 20 66 69 72 73  ssary.  The firs
15730 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
15740 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  ould pointer to 
15750 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
15760 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
15770 79 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20  y that.** is at 
15780 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
15790 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65   of memory, othe
157a0 72 77 69 73 65 20 73 75 62 73 65 71 75 65 6e 74  rwise subsequent
157b0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
157c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53  undefined..** ^S
157d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
157e0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
157f0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
15800 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
15810 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
15820 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
15830 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
15840 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
15850 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
15860 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
15870 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
15880 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
15890 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
158a0 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
158b0 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
158c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
158d0 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
158e0 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
158f0 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a   space.</dd>.**.
15900 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15910 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
15920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15930 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15940 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15950 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
15960 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
15970 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
15980 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
15990 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
159a0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
159b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
159c0 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
159d0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
159e0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
159f0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
15a00 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
15a10 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
15a20 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
15a30 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
15a40 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15a50 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15a60 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
15a70 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
15a80 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
15a90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
15aa0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
15ab0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
15ac0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
15ad0 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
15ae0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
15af0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
15b00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15b10 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
15b20 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
15b30 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
15b40 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15b50 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
15b60 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
15b70 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
15b80 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
15b90 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
15ba0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15bb0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
15bc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
15bd0 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
15be0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
15bf0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15c00 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
15c10 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
15c20 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
15c30 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
15c40 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
15c50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15c60 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
15c70 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
15c80 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
15c90 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
15ca0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
15cb0 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
15cc0 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
15cd0 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
15ce0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15cf0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
15d00 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15d10 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
15d20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
15d30 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
15d40 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
15d50 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
15d60 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
15d70 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
15d80 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15d90 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
15da0 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
15db0 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
15dc0 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
15dd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15de0 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
15df0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
15e00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15e10 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
15e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15e30 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15e40 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15e50 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
15e60 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15e70 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15e80 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
15e90 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15eb0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15ec0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
15ed0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
15ee0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
15ef0 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
15f00 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
15f10 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
15f20 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15f30 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
15f40 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
15f50 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
15f60 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
15f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15f80 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15f90 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
15fa0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
15fc0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
15fd0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15fe0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15ff0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
16000 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
16010 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
16020 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
16030 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
16040 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
16050 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
16060 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
16070 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
16080 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
16090 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
160a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
160b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
160c0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
160d0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
160e0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
160f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16100 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
16110 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
16120 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
16130 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
16140 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
16150 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16160 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
16170 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16180 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
16190 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
161a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
161b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
161c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
161d0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
161e0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
161f0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
16200 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
16210 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
16220 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
16230 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
16240 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
16250 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
16260 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
16270 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
16280 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
16290 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
162a0 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
162b0 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
162c0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
162d0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
162e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
162f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
16300 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
16310 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
16320 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16330 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
16340 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
16350 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
16360 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
16370 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16380 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16390 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
163a0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
163b0 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
163c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
163d0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
163e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
163f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16400 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16410 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
16420 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16430 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
16440 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16450 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
16460 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
16470 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
16480 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
16490 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
164a0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
164b0 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
164c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
164d0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
164e0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
164f0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
16500 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
16510 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
16520 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16530 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
16540 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
16550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
16560 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
16570 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
16580 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
16590 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
165a0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
165b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
165c0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
165d0 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
165e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
165f0 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
16600 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
16610 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
16620 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
16630 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
16640 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16650 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16660 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
16670 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
16680 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16690 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
166a0 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
166b0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
166c0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
166d0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
166e0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
166f0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16700 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
16710 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
16720 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
16730 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
16740 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
16750 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
16760 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
16770 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
16780 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16790 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
167a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
167b0 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
167c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
167d0 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
167e0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16800 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
16810 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16820 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
16830 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16840 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16850 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16860 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
16870 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
16880 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
16890 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
168a0 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
168b0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
168c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
168d0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
168e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
168f0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
16900 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
16910 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
16920 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
16930 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
16940 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
16950 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
16960 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
16970 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16980 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
16990 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
169a0 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
169b0 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
169c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
169d0 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
169e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
169f0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
16a00 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
16a10 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
16a20 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
16a30 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
16a40 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
16a50 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
16a60 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
16a70 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
16a80 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
16a90 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
16aa0 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
16ab0 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
16ac0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
16ad0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16ae0 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
16af0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
16b00 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
16b10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16b20 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
16b30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
16b40 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
16b50 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
16b60 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
16b70 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
16b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16b90 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16ba0 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
16bb0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16bc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
16bd0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
16be0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
16bf0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
16c00 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
16c10 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
16c20 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
16c30 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
16c40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16c50 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
16c60 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
16c70 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
16c80 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
16c90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16ca0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
16cb0 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
16cc0 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
16cd0 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
16ce0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
16cf0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
16d00 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
16d10 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
16d20 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
16d30 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
16d40 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
16d50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16d60 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16d70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16d80 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
16d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
16db0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16dc0 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
16dd0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16de0 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
16df0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16e00 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
16e10 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
16e20 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
16e30 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16e40 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
16e50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
16e60 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
16e70 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16e80 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
16e90 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
16ea0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
16eb0 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
16ec0 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
16ed0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
16ee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
16ef0 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
16f00 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
16f10 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
16f20 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
16f30 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
16f40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16f50 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
16f60 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
16f70 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
16f80 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
16f90 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
16fa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
16fb0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16fc0 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
16fd0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
16fe0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
16ff0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
17000 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
17010 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
17020 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
17030 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17040 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
17050 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
17060 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
17070 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
17080 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
17090 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
170a0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
170b0 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
170c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
170d0 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
170e0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
170f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17100 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17110 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
17120 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
17130 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
17140 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17150 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
17160 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
17170 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
17180 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
17190 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
171a0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
171b0 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
171c0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
171d0 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
171e0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
171f0 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
17200 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
17210 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
17220 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
17230 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
17240 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
17250 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
17260 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
17270 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17280 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
17290 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
172a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
172b0 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
172c0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
172d0 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
172e0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
172f0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
17300 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
17310 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
17320 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
17330 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
17340 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
17350 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
17360 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
17370 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
17380 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
17390 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
173a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
173b0 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
173c0 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
173d0 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
173e0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
173f0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
17400 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
17410 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
17420 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17430 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
17440 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
17450 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17460 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
17470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17480 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
17490 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
174a0 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
174b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
174c0 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
174d0 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
174e0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
174f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
17500 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
17510 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
17520 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17530 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
17540 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17550 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
17560 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
17570 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
17580 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
17590 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
175a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
175b0 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
175c0 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
175d0 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
175e0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
175f0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
17600 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
17610 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
17620 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
17630 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
17640 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
17650 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
17660 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
17670 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
17680 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
17690 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
176a0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
176b0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
176c0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
176d0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
176e0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
176f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17700 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
17710 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17720 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
17730 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
17740 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
17750 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
17760 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
17770 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
17780 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
17790 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
177a0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
177b0 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
177c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
177d0 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
177e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
177f0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
17800 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
17810 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
17820 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
17830 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
17840 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
17850 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
17860 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
17870 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17880 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
17890 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
178a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
178b0 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
178c0 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
178d0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
178e0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
178f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
17900 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
17910 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
17920 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
17930 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
17940 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
17950 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
17960 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17970 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
17980 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17990 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
179a0 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
179b0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
179c0 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
179d0 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
179e0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
179f0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
17a00 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
17a10 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
17a20 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
17a30 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
17a40 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
17a50 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
17a60 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
17a70 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
17a80 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
17a90 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
17aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ab0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
17ac0 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
17ad0 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
17ae0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
17af0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
17b00 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
17b10 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
17b20 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
17b30 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
17b40 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
17b50 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
17b60 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
17b70 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
17b80 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
17b90 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
17ba0 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
17bb0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17bc0 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
17bd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17be0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
17bf0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
17c00 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
17c10 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
17c20 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
17c30 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
17c40 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
17c50 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
17c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17c70 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
17c80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17c90 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17ca0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
17cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17cc0 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
17cd0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17ce0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17cf0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
17d00 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
17d10 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
17d20 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
17d30 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
17d40 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
17d50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17d60 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
17d70 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
17d80 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
17d90 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
17da0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
17db0 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
17dc0 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
17dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17de0 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
17df0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17e00 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
17e10 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17e20 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17e30 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17e40 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17e50 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17e70 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
17e80 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
17e90 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
17ea0 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
17eb0 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
17ec0 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
17ed0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
17ee0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
17ef0 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
17f00 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
17f10 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
17f20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
17f30 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
17f40 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
17f50 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
17f60 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
17f70 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
17f80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17f90 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
17fa0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17fb0 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
17fc0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17fd0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17fe0 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
17ff0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
18000 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
18010 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
18020 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
18030 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
18040 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
18050 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
18060 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
18070 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
18080 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
18090 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
180a0 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
180b0 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
180c0 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
180d0 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
180e0 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
180f0 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
18100 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
18110 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
18120 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
18130 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
18140 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
18150 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
18160 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
18170 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
18180 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
18190 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
181a0 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
181b0 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  value..** </dl>.
181c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
181d0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
181e0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
181f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18200 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
18210 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
18220 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18230 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
18240 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
18250 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
18270 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
18280 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
18290 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
182a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
182b0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
182c0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
182d0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
182e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
182f0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
18300 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18310 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18320 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18330 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
18340 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
18350 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
18360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18370 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
18380 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
18390 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
183a0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
183b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
183c0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
183d0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
183e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
183f0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
18400 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18410 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
18420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18430 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
18440 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
18450 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
18460 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
18470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
18480 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
18490 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
184a0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
184b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
184c0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
184d0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
184e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
184f0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
18500 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
18510 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18520 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
18530 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
18540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18550 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
18560 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
18570 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
18580 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18590 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
185a0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
185b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185c0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
185d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
185e0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
185f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18600 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
18610 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
18620 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
18630 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
18650 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
18660 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
18670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18680 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
18690 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
186a0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
186b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
186c0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
186d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
186e0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
186f0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
18700 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
18710 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
18720 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
18730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18740 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
18750 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
18760 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
18770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18780 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
18790 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
187a0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
187b0 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  Pma */../*.** CA
187c0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
187d0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
187e0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
187f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
18800 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
18810 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
18820 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
18830 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
18840 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
18850 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18860 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
18870 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18880 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
18890 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
188a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
188b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
188c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
188d0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
188e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
188f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
18900 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
18910 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
18920 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
18930 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
18940 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
18950 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
18960 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
18970 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
18980 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
18990 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
189a0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
189b0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
189c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
189d0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
189e0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
189f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18a00 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
18a10 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
18a20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18a30 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
18a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18a50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
18a60 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
18a70 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
18a80 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
18a90 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
18aa0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
18ab0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
18ac0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18ad0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
18ae0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18af0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
18b00 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
18b10 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
18b20 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
18b30 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
18b40 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
18b50 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
18b60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
18b70 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
18b80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18b90 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
18ba0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
18bb0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
18bc0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
18bd0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
18be0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
18bf0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
18c00 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
18c10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
18c20 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
18c30 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
18c40 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
18c50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
18c60 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
18c70 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
18c80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
18c90 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
18ca0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
18cb0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
18cc0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
18cd0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
18ce0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
18cf0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
18d00 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
18d10 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
18d20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
18d30 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
18d40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
18d50 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
18d60 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
18d70 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
18d80 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
18d90 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
18da0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
18db0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
18dc0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
18dd0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18de0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
18df0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
18e00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
18e10 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
18e20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
18e30 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
18e40 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
18e50 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
18e60 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
18e70 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
18e80 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
18e90 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
18ea0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
18eb0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
18ec0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
18ed0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
18ee0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
18ef0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
18f00 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
18f10 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
18f20 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
18f30 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
18f40 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
18f50 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
18f60 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
18f70 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
18f80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18f90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18fa0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
18fb0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18fc0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18fd0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18fe0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
18ff0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
19000 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
19010 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
19020 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
19030 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19040 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19050 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
19060 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
19070 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
19080 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
19090 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
190a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
190b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
190c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
190d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
190e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
190f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
19100 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
19110 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
19120 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
19130 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
19140 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
19150 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
19160 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19170 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19190 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
191a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
191b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
191c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
191d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
191e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
191f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19200 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
19210 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
19220 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
19230 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19240 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
19250 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19260 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
19270 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19280 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19290 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
192a0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
192b0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
192c0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
192d0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
192e0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
192f0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
19300 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
19310 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
19320 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
19330 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19340 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19350 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19360 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
19370 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19380 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
19390 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
193a0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
193b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
193c0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
193d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
193e0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
193f0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
19400 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
19410 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19420 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19430 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
19440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19450 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19460 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
19470 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
19480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19490 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
194a0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
194b0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
194c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
194d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
194e0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
194f0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
19500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19510 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
19520 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
19530 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
19540 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
19560 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19570 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
19580 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
19590 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
195a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
195b0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
195c0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
195d0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
195e0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
195f0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
19600 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
19610 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
19620 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
19630 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
19640 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
19650 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
19660 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
19670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
19680 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
19690 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
196a0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
196b0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
196c0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
196d0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
196e0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
196f0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
19700 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
19710 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
19720 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
19730 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
19740 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
19750 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
19760 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
19770 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
19780 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
19790 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
197a0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
197b0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
197c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
197d0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
197e0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
197f0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
19800 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
19810 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
19820 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
19830 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
19840 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
19850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19860 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19870 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
19880 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
19890 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
198a0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
198b0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
198c0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
198d0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
198e0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
198f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
19900 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
19910 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
19920 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
19930 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
19940 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
19950 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
19960 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
19970 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
19980 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
19990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
199a0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
199b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
199c0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
199d0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
199e0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
199f0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
19a00 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
19a10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
19a20 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
19a30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
19a40 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
19a50 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
19a60 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
19a70 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19a80 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
19a90 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
19aa0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
19ab0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
19ac0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
19ad0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
19ae0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
19af0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
19b00 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
19b10 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
19b20 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
19b30 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
19b40 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
19b50 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
19b60 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
19b70 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
19b80 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
19b90 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
19ba0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
19bb0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
19bc0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19bd0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
19be0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
19bf0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
19c00 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
19c10 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
19c20 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
19c30 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
19c40 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
19c50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19c60 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
19c70 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
19c80 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
19c90 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
19ca0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
19cb0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
19cc0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
19cd0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
19ce0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
19cf0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
19d00 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
19d10 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
19d20 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
19d30 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
19d40 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
19d50 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
19d60 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
19d70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19d80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
19d90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
19da0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
19db0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
19dc0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
19dd0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
19de0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
19df0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
19e00 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
19e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
19e20 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
19e30 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
19e40 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
19e50 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
19e60 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
19e70 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
19e80 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
19e90 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
19ea0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
19eb0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
19ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
19ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
19ee0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19ef0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
19f00 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
19f10 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
19f20 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
19f30 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
19f40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19f50 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
19f60 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19f70 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
19f80 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
19f90 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
19fa0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
19fb0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
19fc0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c   [rowid]..*/.SQL
19fd0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
19fe0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
19ff0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73  CALL sqlite3_las
1a000 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
1a010 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a020 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1a030 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1a040 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a050 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a060 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a070 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a080 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a090 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1a0a0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a0b0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1a0c0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1a0d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a0e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1a0f0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1a100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a110 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1a120 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1a130 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1a140 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1a150 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1a160 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1a170 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1a180 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1a190 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1a1a0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1a1b0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1a1c0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a1d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a1e0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1a1f0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1a200 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1a210 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1a220 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1a230 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1a240 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1a250 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1a260 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1a270 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a280 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1a290 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1a2a0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1a2b0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1a2c0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1a2d0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1a2e0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1a2f0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1a300 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a310 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1a320 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1a330 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1a340 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1a350 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1a360 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1a370 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1a380 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1a390 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1a3a0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1a3b0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1a3c0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1a3d0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a3e0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1a3f0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1a400 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1a410 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1a420 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1a430 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1a440 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1a450 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a460 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1a470 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1a480 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1a490 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1a4a0 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1a4b0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1a4c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1a4d0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1a4e0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1a4f0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1a500 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1a510 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1a520 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1a530 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1a540 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1a550 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1a560 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1a570 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1a580 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1a590 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1a5a0 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1a5b0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1a5c0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1a5d0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1a5e0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1a5f0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1a600 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a610 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1a620 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1a630 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1a640 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1a650 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1a660 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1a670 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1a680 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1a690 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1a6a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a6b0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1a6c0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1a6d0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1a6e0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1a6f0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1a700 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1a710 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1a720 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1a730 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1a740 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1a750 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1a760 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1a770 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1a780 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1a790 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1a7a0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1a7b0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1a7c0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1a7d0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1a7e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1a7f0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1a800 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1a810 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1a820 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1a830 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1a840 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a850 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1a860 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1a870 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1a880 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1a890 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a8a0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1a8b0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1a8c0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
1a8d0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1a8e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a8f0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1a900 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1a910 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1a920 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
1a930 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a940 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a950 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1a960 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1a970 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1a980 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1a990 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1a9a0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a9b0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a9c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1a9d0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a9e0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a9f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1aa00 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1aa10 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  LL sqlite3_chang
1aa20 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1aa30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1aa40 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1aa50 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1aa60 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1aa70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1aa80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1aa90 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1aaa0 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1aab0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1aac0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1aad0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1aae0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1aaf0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1ab00 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1ab10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab20 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1ab30 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1ab40 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1ab50 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1ab60 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1ab70 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1ab80 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1ab90 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1aba0 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1abb0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1abc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1abd0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1abe0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1abf0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1ac00 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1ac10 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1ac20 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1ac30 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1ac40 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1ac50 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1ac60 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1ac70 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1ac80 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1ac90 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1aca0 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1acb0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1acc0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1acd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1ace0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1acf0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1ad00 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1ad10 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1ad20 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1ad30 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1ad40 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1ad50 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1ad60 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1ad70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ad80 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1ad90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1ada0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1adb0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1adc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1add0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1ade0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1adf0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1ae00 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1ae10 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  LL sqlite3_total
1ae20 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1ae30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1ae40 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1ae50 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1ae60 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
1ae70 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1ae80 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1ae90 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1aea0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1aeb0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1aec0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1aed0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1aee0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1aef0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1af00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1af10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1af20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1af30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1af40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1af50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1af60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1af70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1af80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1af90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1afa0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1afb0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1afc0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1afd0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1afe0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1aff0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1b000 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1b010 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1b020 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1b030 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1b040 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1b050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1b060 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1b070 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1b080 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1b090 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1b0a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1b0b0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1b0c0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1b0d0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1b0e0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1b0f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1b100 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1b110 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1b120 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1b130 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1b140 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1b150 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1b160 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1b170 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1b180 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1b190 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1b1a0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1b1b0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1b1c0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1b1d0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1b1e0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1b1f0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1b200 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1b210 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1b220 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1b230 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1b240 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1b250 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1b260 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1b270 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b280 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1b290 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1b2a0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1b2b0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1b2c0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1b2d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1b2e0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1b2f0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1b300 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1b310 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1b320 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b330 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1b340 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1b350 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1b360 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1b370 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1b380 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1b390 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1b3a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1b3b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1b3c0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1b3d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1b3e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1b3f0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1b400 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1b410 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1b420 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1b430 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1b440 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1b450 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1b460 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1b470 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1b480 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1b490 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1b4a0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1b4b0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1b4c0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1b4d0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1b4e0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1b4f0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b500 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1b510 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
1b520 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b530 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
1b540 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
1b550 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
1b560 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
1b570 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
1b580 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51  ly happen..*/.SQ
1b590 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1b5a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1b5b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
1b5c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1b5d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
1b5e0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
1b5f0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
1b600 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
1b610 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1b620 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
1b630 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
1b640 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
1b650 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
1b660 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
1b670 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
1b680 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1b690 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
1b6a0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
1b6b0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
1b6c0 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
1b6d0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
1b6e0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
1b6f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1b700 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
1b710 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
1b720 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
1b730 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1b740 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
1b750 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
1b760 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
1b770 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
1b780 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
1b790 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
1b7a0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
1b7b0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
1b7c0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
1b7d0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
1b7e0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
1b7f0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
1b800 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
1b810 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
1b820 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
1b830 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
1b840 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
1b850 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
1b860 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
1b870 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
1b880 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
1b890 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
1b8a0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
1b8b0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
1b8c0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
1b8d0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
1b8e0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
1b8f0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
1b900 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
1b910 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1b920 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
1b930 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
1b940 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
1b950 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b960 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
1b970 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
1b980 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
1b990 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
1b9a0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
1b9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
1b9c0 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
1b9d0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
1b9e0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
1b9f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
1ba00 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
1ba10 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
1ba20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
1ba30 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
1ba40 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
1ba50 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ba60 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
1ba70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
1ba80 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
1ba90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
1baa0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1bab0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
1bac0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
1bad0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
1bae0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1baf0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
1bb00 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
1bb10 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
1bb20 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1bb30 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
1bb40 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
1bb50 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
1bb60 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1bb70 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
1bb80 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1bb90 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
1bba0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1bbb0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1bbc0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1bbd0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1bbe0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1bbf0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1bc00 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1bc10 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1bc20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1bc30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1bc40 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1bc50 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
1bc60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1bc70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
1bc80 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1bc90 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1bca0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1bcb0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1bcc0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1bcd0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1bce0 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1bcf0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1bd00 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1bd10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1bd20 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1bd30 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1bd40 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1bd50 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1bd60 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1bd70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1bd80 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1bd90 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1bda0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1bdb0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1bdc0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1bdd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1bde0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1bdf0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1be00 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1be10 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1be20 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1be30 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1be40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1be50 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1be60 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1be70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1be80 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1be90 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1bea0 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1beb0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1bec0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1bed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1bee0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1bef0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1bf00 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1bf10 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1bf20 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1bf30 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1bf40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1bf50 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1bf60 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1bf70 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1bf80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1bf90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1bfa0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1bfb0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1bfc0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1bfd0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1bfe0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1bff0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1c000 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c010 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1c020 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c030 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1c040 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1c050 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1c060 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1c070 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1c080 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1c090 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1c0a0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1c0b0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1c0c0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1c0d0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1c0e0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1c0f0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1c100 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1c110 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1c120 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c130 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1c140 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1c150 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1c160 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1c170 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1c180 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1c190 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1c1a0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1c1b0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1c1c0 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1c1d0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1c1e0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1c1f0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1c200 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1c210 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1c220 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1c230 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1c240 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1c250 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1c260 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1c270 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1c280 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c290 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1c2a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1c2b0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1c2c0 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1c2d0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1c2e0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1c2f0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1c300 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1c310 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1c320 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1c330 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1c340 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1c350 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1c360 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1c370 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1c380 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1c390 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1c3a0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1c3b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1c3c0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1c3d0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1c3e0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1c3f0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1c400 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1c410 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1c420 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1c430 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1c440 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1c450 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1c460 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1c470 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1c480 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1c490 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1c4a0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1c4b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1c4c0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1c4d0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1c4e0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1c4f0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1c500 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1c510 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1c520 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1c530 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1c540 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1c550 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1c560 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1c570 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1c580 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1c590 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1c5a0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1c5b0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1c5c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c5d0 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1c5e0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1c5f0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1c600 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1c610 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1c620 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1c630 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1c640 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1c650 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1c660 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1c670 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1c680 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1c690 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1c6a0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1c6b0 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1c6c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1c6d0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1c6e0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1c6f0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1c700 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1c710 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c720 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1c730 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1c740 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1c750 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c760 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1c770 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1c780 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1c790 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1c7a0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1c7b0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1c7c0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1c7d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c7e0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1c7f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1c800 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1c810 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1c820 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1c830 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1c840 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c850 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1c860 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
1c870 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1c880 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1c890 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d  usy Timeout.** M
1c8a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c8b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1c8c0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
1c8d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
1c8e0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
1c8f0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
1c900 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
1c910 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
1c920 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
1c930 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
1c940 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
1c950 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
1c960 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
1c970 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1c980 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
1c990 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
1c9a0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
1c9b0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1c9c0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1c9d0 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1c9e0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1c9f0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1ca00 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1ca10 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1ca20 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  USY]..**.** ^Cal
1ca30 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1ca40 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1ca50 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1ca60 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1ca70 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1ca80 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1ca90 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1caa0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1cab0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1cac0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1cad0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1cae0 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67  ection] at any g
1caf0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
1cb00 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
1cb10 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
1cb20 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
1cb30 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1cb40 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
1cb50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
1cb60 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
1cb70 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1cb80 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
1cb90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
1cba0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1cbb0 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eout].*/.SQLITE_
1cbc0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1cbd0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
1cbe0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1cbf0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1cc00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cc10 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1cc20 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1cc30 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1cc40 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1cc50 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1cc60 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1cc70 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1cc80 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1cc90 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1cca0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1ccb0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1ccc0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1ccd0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1cce0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1ccf0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1cd00 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1cd10 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1cd20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1cd30 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1cd40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1cd50 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1cd60 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1cd70 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1cd80 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1cd90 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1cda0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1cdb0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1cdc0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1cdd0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1cde0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1cdf0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1ce00 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1ce10 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1ce20 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1ce30 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1ce40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1ce50 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1ce60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1ce70 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1ce80 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1ce90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1cea0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1ceb0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1cec0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1ced0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1cee0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1cef0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1cf00 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1cf10 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1cf20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1cf30 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1cf40 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1cf50 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1cf60 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1cf70 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1cf80 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1cf90 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1cfa0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1cfb0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1cfc0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1cfd0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1cfe0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1cff0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1d000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1d010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1d020 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1d030 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1d040 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1d050 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1d060 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1d070 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1d080 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1d090 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1d0a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1d0b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1d0c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1d0d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1d0e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1d0f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1d100 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1d110 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1d120 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1d130 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1d140 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1d150 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1d160 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d170 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1d180 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1d190 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1d1a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1d1b0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1d1c0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1d1d0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1d1e0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1d1f0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1d200 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d210 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1d220 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1d230 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1d240 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1d250 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1d260 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1d270 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1d280 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1d290 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1d2a0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1d2b0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1d2c0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1d2d0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1d2e0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d2f0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1d300 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1d310 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1d320 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1d330 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1d340 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d350 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1d360 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d370 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1d380 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d390 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1d3a0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1d3b0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1d3c0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1d3d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1d3e0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1d3f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d400 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1d410 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d420 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1d430 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d440 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1d450 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1d460 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1d470 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1d480 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1d490 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d4a0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1d4b0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1d4c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1d4d0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1d4e0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1d4f0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1d500 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1d510 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1d520 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1d530 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1d540 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1d550 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d560 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1d570 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1d580 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1d590 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d5a0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1d5b0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1d5c0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1d5d0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1d5e0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1d5f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1d600 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1d610 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1d620 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1d630 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1d640 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1d650 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1d660 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1d670 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1d680 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1d690 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1d6a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d6b0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1d6c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1d6d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d6e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1d6f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1d700 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1d710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d720 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1d730 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1d740 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1d750 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1d760 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1d770 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1d780 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1d790 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1d7a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1d7b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1d7c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1d7d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1d7e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1d7f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1d800 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1d810 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1d820 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1d830 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1d840 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1d860 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1d870 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d880 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1d890 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1d8a0 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  LL sqlite3_get_t
1d8b0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1d8c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1d8d0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1d8e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1d8f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1d900 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1d910 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1d920 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1d930 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1d940 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1d950 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1d960 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1d970 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1d980 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1d990 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1d9a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1d9b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1d9c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d9d0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1d9e0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1d9f0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1da00 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1da10 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
1da20 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72  DCALL sqlite3_fr
1da30 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1da40 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1da50 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1da60 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1da70 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1da80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1da90 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1daa0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1dab0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1dac0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1dad0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1dae0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1daf0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1db00 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1db10 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1db20 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1db30 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1db40 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1db50 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1db60 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1db70 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1db80 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1db90 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1dba0 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1dbb0 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1dbc0 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1dbd0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1dbe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1dbf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dc00 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1dc10 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1dc20 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1dc30 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1dc40 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1dc50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1dc60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dc70 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1dc80 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1dc90 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1dca0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1dcb0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1dcc0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1dcd0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1dce0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1dcf0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1dd00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1dd10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1dd20 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1dd30 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1dd40 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1dd50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1dd60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1dd70 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1dd80 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1dd90 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1dda0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ddb0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ddc0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ddd0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1dde0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ddf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1de00 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1de10 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1de20 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1de30 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1de40 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1de50 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1de60 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1de70 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1de80 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1de90 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1dea0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1deb0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1dec0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1ded0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1dee0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1def0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1df00 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1df10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1df20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1df30 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1df40 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1df50 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1df60 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1df70 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1df80 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1df90 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1dfa0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1dfb0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1dfc0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1dfd0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1dfe0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1dff0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1e000 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1e010 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1e020 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1e030 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1e040 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1e050 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1e060 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1e070 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1e080 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1e090 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1e0a0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1e0b0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1e0c0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1e0d0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1e0e0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1e0f0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1e100 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1e110 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1e120 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1e130 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1e140 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1e150 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1e160 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1e170 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1e180 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1e190 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1e1a0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1e1b0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1e1c0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1e1d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1e1e0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1e1f0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1e200 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1e210 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1e220 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1e230 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1e240 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1e250 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1e260 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1e270 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1e280 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1e290 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1e2a0 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1e2b0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1e2c0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1e2d0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1e2e0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1e2f0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1e300 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1e310 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1e320 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1e330 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1e340 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1e350 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1e360 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1e370 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1e380 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1e390 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1e3a0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1e3b0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1e3c0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1e3d0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1e3e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1e3f0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1e400 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1e410 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1e420 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1e430 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1e440 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e450 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e460 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1e470 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e480 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1e490 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e4a0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1e4b0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1e4c0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1e4d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e4e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e4f0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e500 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e510 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e520 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1e530 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e540 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e550 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e560 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e570 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e580 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e590 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1e5a0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1e5b0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1e5c0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1e5d0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1e5e0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1e5f0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1e600 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e610 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e620 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e630 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e640 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1e650 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1e660 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e670 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1e680 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1e690 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1e6a0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1e6b0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1e6c0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1e6d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e6e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e6f0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e700 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1e710 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1e720 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e730 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e740 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1e750 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1e760 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1e770 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1e780 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1e790 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1e7a0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1e7b0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1e7c0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1e7d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1e7e0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e7f0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1e800 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1e810 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1e820 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1e830 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1e840 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1e850 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e860 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1e870 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1e880 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1e890 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1e8a0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1e8b0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1e8c0 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1e8d0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1e8e0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1e8f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e900 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e910 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e920 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e930 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1e940 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e950 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e960 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e970 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e980 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e990 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e9a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1e9b0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1e9c0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1e9d0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1e9e0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1e9f0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1ea00 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1ea10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1ea20 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1ea30 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ea40 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1ea50 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1ea60 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1ea70 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1ea80 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1ea90 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1eaa0 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1eab0 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1eac0 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1ead0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1eae0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1eaf0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1eb00 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1eb10 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1eb20 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1eb30 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1eb40 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1eb50 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1eb60 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1eb70 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1eb80 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1eb90 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1eba0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1ebb0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1ebc0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1ebd0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1ebe0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1ebf0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1ec00 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1ec10 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1ec20 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1ec30 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c  string.)^.*/.SQL
1ec40 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1ec50 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
1ec60 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1ec70 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1ec80 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1ec90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1eca0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1ecb0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1ecc0 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  st);.SQLITE_API 
1ecd0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45  char *SQLITE_CDE
1ece0 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  CL sqlite3_snpri
1ecf0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1ed00 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1ed10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1ed20 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ed30 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1ed40 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1ed50 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1ed60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ed70 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1ed80 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1ed90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1eda0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1edb0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1edc0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1edd0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1ede0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1edf0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1ee00 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1ee10 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1ee20 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1ee30 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1ee40 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1ee50 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1ee60 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1ee70 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1ee80 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1ee90 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1eea0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1eeb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1eec0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1eed0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1eee0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1eef0 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1ef00 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1ef10 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1ef20 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1ef30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ef40 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1ef50 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1ef60 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1ef70 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1ef80 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1ef90 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1efa0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1efb0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1efc0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1efd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1efe0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1eff0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1f000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1f010 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e  lloc64(N) routin
1f020 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b  e works just lik
1f030 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  e.** sqlite3_mal
1f040 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68  loc(N) except th
1f050 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67  at N is an unsig
1f060 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ned 64-bit integ
1f070 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1f080 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74   a signed 32-bit
1f090 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1f0a0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1f0b0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1f0c0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1f0d0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1f0e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f0f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1f100 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1f110 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1f120 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1f130 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1f140 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1f150 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1f160 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1f170 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1f180 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1f190 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1f1a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1f1b0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1f1c0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1f1d0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1f1e0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1f1f0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1f200 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1f210 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1f220 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1f230 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1f240 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1f250 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1f260 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1f270 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1f280 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1f290 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1f2a0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1f2b0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1f2c0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1f2d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1f2e0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1f2f0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1f300 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1f310 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1f320 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f330 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
1f340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f350 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  ,N) interface at
1f360 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1f370 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1f380 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20  ry allocation X 
1f390 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1f3a0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
1f3b0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
1f3c0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1f3d0 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e  c(X,N).** is a N
1f3e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1f3f0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1f400 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1f410 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1f420 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e  _malloc(N)..** ^
1f430 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
1f440 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1f450 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65  alloc(X,N) is ze
1f460 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1f470 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1f480 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1f490 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1f4a0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1f4b0 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  ee(X)..** ^sqlit
1f4c0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f4d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1f4e0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1f4f0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1f500 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1f510 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1f520 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
1f530 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61  memory is availa
1f540 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1f550 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1f560 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f570 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1f580 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1f590 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f5a0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1f5b0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1f5c0 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1f5d0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1f5e0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e  _realloc(X,N) an
1f5f0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1f600 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1f610 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1f620 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1f630 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  urns NULL and N 
1f640 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
1f650 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61  n the.** prior a
1f660 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74  llocation is not
1f670 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1f680 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1f690 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66  oc64(X,N) interf
1f6a0 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73  aces works the s
1f6b0 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
1f6c0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65  3_realloc(X,N) e
1f6d0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1f6e0 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
1f6f0 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  d integer instea
1f700 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74  d.** of a 32-bit
1f710 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e   signed integer.
1f720 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20  .**.** ^If X is 
1f730 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1f740 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  ion previously o
1f750 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1f760 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a  ite3_malloc(),.*
1f770 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f780 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  64(), sqlite3_re
1f790 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69  alloc(), or sqli
1f7a0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c  te3_realloc64(),
1f7b0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f7c0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f7d0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1f7e0 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  at memory alloca
1f7f0 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a  tion in bytes..*
1f800 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
1f810 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1f820 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20  _msize(X) might 
1f830 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
1f840 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
1f850 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20  bytes requested 
1f860 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63  when X was alloc
1f870 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20  ated.  ^If X is 
1f880 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1f890 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1f8a0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1f8b0 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e  zero.  If X poin
1f8c0 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20  ts to something 
1f8d0 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  that is not.** t
1f8e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1f8f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f900 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e  n, or if it poin
1f910 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79  ts to a formerly
1f920 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79  .** valid memory
1f930 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74   allocation that
1f940 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72   has now been fr
1f950 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  eed, then the be
1f960 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c  havior.** of sql
1f970 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73  ite3_msize(X) is
1f980 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1f990 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e  ossibly harmful.
1f9a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1f9b0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1f9c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f9d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f9e0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1f9f0 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73  alloc64(), and s
1fa00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1fa10 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1fa20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1fa30 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1fa40 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1fa50 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1fa60 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1fa70 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1fa80 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1fa90 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1faa0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1fab0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1fac0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1fad0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1fae0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1faf0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1fb00 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1fb10 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1fb20 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1fb30 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1fb40 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1fb50 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1fb60 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1fb70 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1fb80 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1fb90 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1fba0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1fbb0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1fbc0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1fbd0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1fbe0 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1fbf0 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1fc00 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1fc10 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1fc20 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1fc30 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1fc40 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1fc50 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1fc60 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1fc70 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1fc80 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1fc90 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1fca0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1fcb0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1fcc0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1fcd0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1fce0 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1fcf0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1fd00 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1fd10 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1fd20 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1fd30 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1fd40 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1fd50 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1fd60 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1fd70 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1fd80 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1fd90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1fda0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1fdb0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1fdc0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1fdd0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1fde0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1fdf0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1fe00 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1fe10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1fe20 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1fe30 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1fe40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1fe50 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1fe60 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1fe70 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1fe80 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1fe90 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1fea0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1feb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1fec0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1fed0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1fee0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1fef0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1ff00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1ff10 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
1ff20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
1ff30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c  CALL sqlite3_mal
1ff40 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1ff50 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
1ff60 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
1ff70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72  TDCALL sqlite3_r
1ff80 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1ff90 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1ffa0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1ffb0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ALL sqlite3_real
1ffc0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1ffd0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51  ite3_uint64);.SQ
1ffe0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1fff0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
20000 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
20010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
20020 69 74 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49  ite3_uint64 SQLI
20030 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
20040 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
20050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20060 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
20070 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
20080 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
20090 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
200a0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
200b0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
200c0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
200d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
200e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
200f0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
20100 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
20110 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
20120 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
20130 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
20140 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
20150 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
20160 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20170 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20180 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20190 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
201a0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
201b0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
201c0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
201d0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
201e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
201f0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
20200 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
20210 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
20220 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20230 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
20240 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20250 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
20260 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
20270 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
20280 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20290 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
202a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
202b0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
202c0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
202d0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
202e0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
202f0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
20300 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
20310 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
20320 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
20330 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
20340 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
20350 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
20360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20370 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
20380 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
20390 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
203a0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
203b0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
203c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
203d0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
203e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
203f0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
20400 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20410 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
20420 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
20430 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
20440 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20450 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
20460 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
20470 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
20480 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
20490 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
204a0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
204b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d  CALL sqlite3_mem
204c0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
204d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
204e0 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
204f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
20500 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20510 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
20520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20530 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
20540 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
20550 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
20560 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
20570 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
20580 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
20590 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
205a0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
205b0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
205c0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
205d0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
205e0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
205f0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
20600 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
20610 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
20620 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
20630 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
20640 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
20650 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
20660 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
20670 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
20680 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
20690 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
206a0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
206b0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
206c0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
206d0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
206e0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
206f0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
20700 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
20710 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61  ..** ^The P para
20720 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e  meter can be a N
20730 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20740 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ** ^If this rout
20750 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ine has not been
20760 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c   previously call
20770 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65  ed or if the pre
20780 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61  vious.** call ha
20790 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e  d N less than on
207a0 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e or a NULL poin
207b0 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20  ter for P, then 
207c0 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73  the PRNG is.** s
207d0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
207e0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20  omness obtained 
207f0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
20800 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a  ness method of.*
20810 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  * the default [s
20820 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20830 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
20840 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
20850 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
20860 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
20870 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d  re and a.** non-
20880 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20  NULL P then the 
20890 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
208a0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
208b0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
208c0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
208d0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
208e0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
208f0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
20900 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20910 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
20920 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
20930 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
20940 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
20950 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
20960 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
20970 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
20980 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
20990 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
209a0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
209b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
209c0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
209d0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
209e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
209f0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
20a00 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
20a10 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
20a20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20a30 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20a40 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20a50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20a60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20a70 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20a80 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
20a90 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
20aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20ab0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
20ac0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20ad0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
20ae0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
20af0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
20b00 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
20b10 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
20b20 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
20b30 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
20b40 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
20b50 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20b60 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
20b70 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
20b80 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
20b90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20ba0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
20bb0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
20bc0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
20bd0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
20be0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
20bf0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
20c00 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
20c10 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
20c20 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
20c30 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
20c40 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
20c50 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
20c60 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
20c70 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
20c80 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
20c90 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
20ca0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20cb0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20cc0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
20cd0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20ce0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
20cf0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
20d00 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
20d10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
20d20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
20d30 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
20d40 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
20d50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
20d60 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
20d70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
20d80 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
20d90 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20da0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
20db0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
20dc0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
20dd0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
20de0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20df0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
20e00 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
20e10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20e20 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
20e30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
20e40 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
20e50 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
20e60 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
20e70 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
20e80 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
20e90 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
20ea0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
20eb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
20ec0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20ed0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
20ee0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
20ef0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
20f00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20f10 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
20f20 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
20f30 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
20f40 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
20f50 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
20f60 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
20f70 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
20f80 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
20f90 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
20fa0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
20fb0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
20fc0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
20fd0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
20fe0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
20ff0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
21000 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
21010 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
21020 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
21030 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21040 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
21050 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
21060 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
21070 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
21080 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21090 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
210a0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
210b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
210c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
210d0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
210e0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
210f0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
21100 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
21110 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
21120 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
21130 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
21140 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
21150 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
21160 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
21170 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
21180 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
21190 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
211a0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
211b0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
211c0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
211d0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
211e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
211f0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21200 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
21210 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21220 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
21230 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
21240 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
21250 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
21260 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
21270 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
21280 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
21290 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
212a0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
212b0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
212c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
212d0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
212e0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
212f0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
21300 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
21310 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21320 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
21330 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
21340 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
21350 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
21360 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
21370 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
21380 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
21390 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
213a0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
213b0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
213c0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
213d0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
213e0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
213f0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
21400 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
21410 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21420 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21430 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21440 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21450 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21460 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21470 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
21480 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
21490 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
214a0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
214b0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
214c0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
214d0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
214e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
214f0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
21500 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
21510 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
21520 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
21530 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21540 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21550 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21560 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
21570 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
21580 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
21590 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
215a0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
215b0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
215c0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
215d0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
215e0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
215f0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
21600 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
21610 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
21620 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
21630 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21640 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21650 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21670 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
21680 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
21690 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
216a0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
216b0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
216c0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
216d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
216e0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
216f0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
21700 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
21710 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
21720 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
21730 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21740 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21750 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21760 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21780 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21790 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
217a0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
217b0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
217c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
217d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
217e0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
217f0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
21800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
21810 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21820 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21830 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21840 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21850 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21860 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21870 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
21880 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21890 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
218a0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
218b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
218c0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
218d0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
218e0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
218f0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
21900 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
21910 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
21920 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
21930 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
21940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21950 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
21960 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
21970 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21980 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
21990 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
219a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
219b0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
219c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
219d0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
219e0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
219f0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
21a00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21a10 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
21a20 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
21a30 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
21a40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21a50 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
21a60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
21a70 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
21a80 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
21a90 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
21aa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
21ab0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
21ac0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
21ad0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
21ae0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
21af0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
21b00 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21b10 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21b20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
21b30 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
21b40 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
21b50 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21b60 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
21b70 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21b80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21b90 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
21ba0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
21bb0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
21bc0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
21bd0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
21be0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
21bf0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
21c00 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
21c10 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
21c20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
21c30 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
21c40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21c50 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
21c60 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
21c70 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
21c80 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21c90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
21ca0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
21cb0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
21cc0 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
21cd0 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
21ce0 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
21cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
21d00 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
21d10 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
21d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21d30 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
21d40 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21d50 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
21d60 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
21d70 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
21d80 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
21d90 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
21da0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
21db0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
21dc0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21dd0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
21de0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21df0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21e00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
21e10 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
21e20 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
21e30 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
21e40 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
21e50 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
21e60 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
21e70 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
21e80 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
21e90 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21ea0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
21eb0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
21ec0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
21ed0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
21ee0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
21ef0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
21f00 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
21f10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
21f20 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
21f30 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
21f40 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
21f50 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
21f60 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
21f70 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
21f80 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
21f90 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
21fa0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21fb0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
21fc0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
21fd0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
21fe0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
21ff0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
22000 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
22010 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
22020 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
22030 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
22040 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
22050 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
22060 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
22070 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
22080 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
22090 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
220a0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
220b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
220c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
220d0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
220e0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
220f0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
22100 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
22110 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
22120 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
22130 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
22140 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
22150 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
22160 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
22170 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
22180 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
221a0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
221b0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
221c0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
221d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
221e0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
221f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22200 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22220 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22230 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
22240 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22270 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22280 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
22290 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
222a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
222b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
222c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
222d0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
222e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
222f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22310 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22320 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
22330 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22340 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22360 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22370 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
22380 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22390 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
223a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
223b0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
223c0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
223d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
223e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
223f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22400 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
22410 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
22420 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
22430 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22450 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
22460 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
22470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
224a0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
224b0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
224c0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
224d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
224e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
224f0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
22500 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
22510 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22540 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
22550 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
22560 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22590 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
225a0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
225b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
225c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
225d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
225e0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
225f0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
22600 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22610 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22620 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22630 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
22640 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
22650 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22660 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22670 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22680 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
22690 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
226a0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
226b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
226c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
226d0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
226e0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
226f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22710 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
22720 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
22730 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22740 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22750 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22760 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
22770 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
22780 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
22790 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
227a0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
227b0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
227c0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
227d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
227e0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
227f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22800 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
22810 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
22820 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22830 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22840 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22850 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
22860 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
22870 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
22880 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
228a0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
228b0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
228c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
228d0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
228e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
228f0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
22900 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
22910 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
22920 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22940 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
22950 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
22960 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
22970 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22990 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
229a0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
229b0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
229c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
229d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
229e0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
229f0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
22a00 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
22a10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
22a30 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
22a40 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
22a50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22a60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22a80 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
22a90 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
22aa0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22ab0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22ad0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
22ae0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
22af0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
22b00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22b10 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
22b20 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
22b30 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
22b40 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
22b50 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
22b60 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
22b70 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
22b80 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22b90 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
22ba0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
22bb0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
22bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
22bd0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
22be0 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
22bf0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
22c00 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
22c10 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22c20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22c30 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
22c40 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
22c50 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
22c60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
22c70 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
22c80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22c90 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
22ca0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
22cb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
22cc0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
22cd0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
22ce0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
22cf0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
22d00 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
22d10 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
22d20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
22d30 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
22d40 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
22d50 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
22d60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
22d70 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
22d80 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
22d90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
22da0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
22db0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
22dc0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
22dd0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
22de0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
22df0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
22e00 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
22e10 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
22e20 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
22e30 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
22e40 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
22e50 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
22e60 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
22e70 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
22e80 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
22e90 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
22ea0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
22eb0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
22ec0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
22ed0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
22ee0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
22ef0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
22f00 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
22f10 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
22f20 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
22f30 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
22f40 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
22f50 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
22f60 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
22f70 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
22f80 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
22f90 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22fa0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
22fb0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
22fc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
22fd0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
22fe0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
22ff0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
23000 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23010 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
23020 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
23030 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
23040 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
23050 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
23060 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
23070 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
23080 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
23090 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
230a0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
230b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
230c0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
230d0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
230e0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
230f0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
23100 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
23110 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
23120 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
23130 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
23140 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
23150 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
23160 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
23170 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
23180 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
23190 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
231a0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
231b0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
231c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
231d0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
231e0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
231f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23200 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
23210 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
23220 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
23230 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23240 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
23250 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
23260 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
23270 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
23280 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
23290 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
232a0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
232b0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
232c0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
232d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
232e0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
232f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
23300 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
23310 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
23320 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
23330 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23340 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
23350 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
23360 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
23370 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
23380 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
23390 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
233a0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
233b0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
233c0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
233d0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
233e0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
233f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
23400 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
23410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23420 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
23430 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
23440 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23450 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23460 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23470 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23480 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23490 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
234a0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
234b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
234c0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
234d0 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
234e0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
234f0 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
23500 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
23510 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
23520 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
23530 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
23540 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23550 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23560 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23570 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
23580 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
23590 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
235a0 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
235b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
235c0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
235d0 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
235e0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
235f0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
23600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23610 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
23620 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23630 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
23640 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
23650 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
23660 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
23670 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23680 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
23690 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
236a0 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
236b0 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
236c0 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
236d0 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
236e0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
236f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23700 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
23710 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
23720 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
23730 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
23740 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23750 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
23760 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
23770 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
23780 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
23790 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
237a0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
237b0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
237c0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
237d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
237e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
237f0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
23800 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
23810 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
23820 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23830 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
23840 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
23850 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23870 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
23880 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
23890 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
238a0 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
238b0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
238c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  ALL sqlite3_prog
238d0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
238e0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
238f0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
23900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23910 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
23920 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
23930 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55  ction.** CONSTRU
23940 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  CTOR: sqlite3.**
23950 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
23960 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
23970 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
23980 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
23990 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
239a0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
239b0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
239c0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
239d0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
239e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
239f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
23a00 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
23a10 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
23a20 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
23a30 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
23a40 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
23a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23a60 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
23a70 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
23a80 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
23a90 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
23aa0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
23ab0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
23ac0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
23ad0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
23ae0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
23af0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
23b00 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
23b10 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
23b20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
23b30 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
23b40 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
23b50 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
23b60 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
23b70 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
23b80 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
23b90 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
23ba0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
23bb0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
23bc0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
23bd0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
23be0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
23bf0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
23c00 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
23c10 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
23c20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
23c30 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
23c40 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
23c50 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
23c60 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
23c70 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
23c80 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
23c90 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
23ca0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
23cb0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
23cc0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f  will be UTF-8 fo
23cd0 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61  r databases crea
23ce0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c  ted using.** sql
23cf0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
23d00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23d10 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
23d20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74  encoding for dat
23d30 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65  abases.** create
23d40 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
23d50 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65  open16() will be
23d60 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
23d70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
23d80 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
23d90 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
23da0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
23db0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
23dc0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
23dd0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
23de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23df0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
23e00 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
23e10 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
23e20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
23e30 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
23e40 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
23e50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23e60 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
23e70 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
23e80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
23e90 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
23ea0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
23eb0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
23ec0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
23ed0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
23ee0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
23ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
23f00 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
23f10 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
23f20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
23f30 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
23f40 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
23f50 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
23f60 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
23f70 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
23f80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
23f90 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
23fa0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
23fb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
23fc0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
23fd0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23fe0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
23ff0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
24000 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
24010 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
24020 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24030 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
24040 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24050 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
24060 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
24070 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
24080 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
24090 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
240a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
240b0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
240c0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
240d0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
240e0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
240f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24100 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
24110 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
24120 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
24130 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
24140 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
24150 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
24160 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
24170 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
24180 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
24190 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
241a0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
241b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
241c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
241d0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
241e0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
241f0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
24200 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24210 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24220 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
24230 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
24240 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
24250 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
24260 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
24270 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
24280 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
24290 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
242a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
242b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
242c0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
242d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
242e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
242f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24300 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
24310 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
24320 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
24330 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
24340 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
24350 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24360 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
24370 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
24380 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
24390 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
243a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
243b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
243c0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
243d0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
243e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
243f0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
24400 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
24410 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
24420 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
24430 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
24440 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
24450 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
24460 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
24470 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
24480 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
24490 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
244a0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
244b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
244c0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
244d0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
244e0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
244f0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
24500 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
24510 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
24520 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
24530 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
24540 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24550 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
24560 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
24570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24580 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
24590 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
245a0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
245b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
245c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
245d0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
245e0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
245f0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
24600 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
24610 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
24620 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
24630 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
24640 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24650 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
24660 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
24670 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
24680 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
24690 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
246a0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
246b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
246c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
246d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
246e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
246f0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
24700 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
24710 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
24720 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
24730 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
24740 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
24750 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
24760 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
24770 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
24780 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
24790 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
247a0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
247b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
247c0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
247d0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
247e0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
247f0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
24800 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
24810 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
24820 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
24830 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
24840 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
24850 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
24860 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
24870 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
24880 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
24890 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
248a0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
248b0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
248c0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
248d0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
248e0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
248f0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
24900 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
24910 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
24920 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
24930 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
24940 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
24950 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
24960 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
24970 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
24980 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
24990 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
249a0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
249b0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
249c0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
249d0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
249e0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
249f0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
24a00 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
24a10 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
24a20 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
24a30 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
24a40 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
24a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
24a60 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
24a70 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
24a80 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
24a90 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
24aa0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
24ab0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
24ac0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
24ad0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
24ae0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
24af0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
24b00 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
24b10 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
24b20 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
24b30 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
24b40 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
24b50 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
24b60 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
24b70 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
24b80 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
24b90 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
24ba0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
24bb0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
24bc0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
24bd0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
24be0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
24bf0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
24c00 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
24c10 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
24c20 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
24c30 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
24c40 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
24c50 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
24c60 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
24c70 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
24c80 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24c90 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
24ca0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
24cb0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
24cc0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
24cd0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
24ce0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
24cf0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
24d00 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
24d10 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
24d20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
24d30 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
24d40 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
24d50 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
24d60 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
24d70 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
24d80 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
24d90 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
24da0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
24db0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
24dc0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
24dd0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
24de0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
24df0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
24e00 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
24e10 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
24e20 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
24e30 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
24e40 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
24e50 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
24e60 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
24e70 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
24e80 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
24e90 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
24ea0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
24eb0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
24ec0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
24ed0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
24ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
24ef0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
24f00 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
24f10 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
24f20 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
24f30 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
24f40 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
24f50 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
24f60 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
24f70 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
24f80 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
24f90 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
24fa0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
24fb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
24fc0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
24fd0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
24fe0 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
24ff0 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
25000 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
25010 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
25020 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
25030 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
25040 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
25050 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
25060 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
25070 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
25080 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
25090 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
250a0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
250b0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
250c0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
250d0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
250e0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
250f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
25100 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
25110 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
25120 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
25130 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
25140 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25150 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25160 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
25170 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
25180 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
25190 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
251a0 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
251b0 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
251c0 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
251d0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
251e0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
251f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
25200 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
25210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25220 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
25230 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
25240 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
25250 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
25260 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
25270 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
25280 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
25290 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
252a0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
252b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
252c0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
252d0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
252e0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
252f0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
25300 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
25310 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
25320 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
25330 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
25340 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
25350 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25360 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25370 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
25380 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
25390 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
253a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
253b0 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
253c0 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
253d0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
253e0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
253f0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
25400 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
25410 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
25420 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
25430 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
25440 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25450 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
25460 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
25470 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
25480 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
25490 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
254a0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
254b0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
254c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
254d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
254e0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
254f0 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
25500 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
25510 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
25520 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
25530 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
25540 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
25550 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
25560 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25570 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
25580 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
25590 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
255a0 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
255b0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
255c0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
255d0 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
255e0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
255f0 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
25600 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
25610 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
25620 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
25630 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
25640 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
25650 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
25660 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
25670 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
25680 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
25690 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
256a0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
256b0 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
256c0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
256d0 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
256e0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
256f0 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
25700 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
25710 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
25720 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
25730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25740 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
25750 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
25760 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
25770 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
25780 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
25790 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
257a0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
257b0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
257c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
257d0 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
257e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
257f0 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
25800 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
25810 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
25820 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
25830 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
25840 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
25850 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
25860 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
25870 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25880 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
25890 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
258a0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
258b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
258c0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
258d0 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
258e0 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
258f0 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
25900 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
25910 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
25920 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
25930 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
25940 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25950 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
25960 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
25970 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
25980 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
25990 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
259a0 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
259b0 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
259c0 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
259d0 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
259e0 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
259f0 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
25a00 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
25a10 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
25a20 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
25a30 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
25a40 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
25a50 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
25a60 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
25a70 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
25a80 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
25a90 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
25aa0 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
25ab0 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
25ac0 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
25ad0 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
25ae0 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
25af0 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
25b00 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
25b10 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
25b20 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
25b30 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
25b40 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
25b50 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
25b60 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
25b70 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
25b80 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
25b90 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
25ba0 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
25bb0 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
25bc0 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
25bd0 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
25be0 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
25bf0 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
25c00 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
25c10 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
25c20 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
25c30 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
25c40 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
25c50 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
25c60 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
25c70 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
25c80 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
25c90 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
25ca0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
25cb0 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
25cc0 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
25cd0 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
25ce0 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
25cf0 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
25d00 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
25d10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
25d20 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
25d30 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
25d40 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
25d50 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
25d60 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
25d70 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
25d80 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
25d90 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
25da0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
25db0 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
25dc0 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
25dd0 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
25de0 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
25df0 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
25e00 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
25e10 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
25e20 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
25e30 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
25e40 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
25e50 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
25e60 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
25e70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
25e80 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
25e90 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
25ea0 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
25eb0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25ec0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
25ed0 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
25ee0 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
25ef0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
25f00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25f10 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
25f20 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
25f30 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
25f40 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
25f50 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
25f60 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
25f70 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
25f80 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
25f90 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
25fa0 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
25fb0 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
25fc0 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
25fd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
25fe0 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
25ff0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
26000 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26010 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
26020 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
26030 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
26040 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
26050 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
26060 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
26070 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
26080 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
26090 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
260a0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
260b0 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
260c0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
260d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
260e0 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
260f0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
26100 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
26110 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26120 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
26130 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
26140 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
26150 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
26160 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
26170 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
26180 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
26190 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
261a0 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
261b0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
261c0 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
261d0 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
261e0 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
261f0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
26200 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
26210 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
26220 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
26230 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
26240 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
26250 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
26260 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
26270 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
26280 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
26290 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
262a0 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
262b0 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
262c0 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
262d0 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
262e0 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
262f0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26300 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
26310 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
26320 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
26330 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
26340 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
26350 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
26360 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
26370 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
26380 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
26390 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
263a0 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
263b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
263c0 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
263d0 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
263e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
263f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26400 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
26410 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
26420 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
26430 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26440 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
26450 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
26460 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
26470 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
26480 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
26490 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
264a0 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
264b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
264c0 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
264d0 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
264e0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
264f0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
26500 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
26510 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
26520 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
26530 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
26540 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
26550 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
26560 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
26570 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
26580 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
26590 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
265a0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
265b0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
265c0 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
265d0 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
265e0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
265f0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
26600 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
26610 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
26620 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
26630 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
26640 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
26650 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
26660 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
26670 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
26680 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
26690 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
266a0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
266b0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
266c0 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
266d0 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
266e0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
266f0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
26700 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
26710 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
26720 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
26730 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
26740 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
26750 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
26760 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26770 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
26780 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
26790 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
267a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
267b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
267c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
267d0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
267e0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
267f0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
26800 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
26810 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
26820 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
26830 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
26840 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
26850 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
26860 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
26870 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
26880 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26890 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
268a0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
268b0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
268c0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
268d0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
268e0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
268f0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
26900 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
26910 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
26920 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
26930 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
26940 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
26950 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
26960 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
26970 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
26980 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
26990 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
269a0 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tory].*/.SQLITE_
269b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
269c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
269d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
269e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
269f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
26a00 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
26a10 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
26a20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
26a30 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
26a40 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
26a50 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
26a60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70  DCALL sqlite3_op
26a70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
26a80 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
26a90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26aa0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
26ab0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26ac0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26ad0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26ae0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
26af0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
26b00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
26b10 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
26b20 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
26b30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
26b40 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
26b50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26b60 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
26b70 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26b80 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
26b90 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
26ba0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
26bb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
26bc0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
26bd0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
26be0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
26bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
26c00 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
26c10 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
26c20 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
26c30 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
26c40 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
26c50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
26c60 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
26c70 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
26c80 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
26c90 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
26ca0 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
26cb0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
26cc0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
26cd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
26ce0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
26cf0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
26d00 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
26d10 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
26d20 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
26d30 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
26d40 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
26d50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
26d60 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
26d70 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
26d80 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
26d90 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
26da0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
26db0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
26dc0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
26dd0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
26de0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
26df0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
26e00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26e10 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
26e20 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
26e30 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
26e40 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
26e50 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
26e60 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
26e70 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
26e80 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
26e90 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
26ea0 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
26eb0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
26ec0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
26ed0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
26ee0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
26ef0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
26f00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
26f10 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
26f20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
26f30 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
26f40 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
26f50 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
26f60 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
26f70 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
26f80 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
26f90 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
26fa0 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
26fb0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
26fc0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
26fd0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
26fe0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
26ff0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
27000 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27010 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
27020 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
27030 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
27040 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
27050 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27060 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
27070 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
27080 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27090 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
270a0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
270b0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
270c0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
270d0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
270e0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
270f0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
27100 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
27110 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
27120 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
27130 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
27140 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
27150 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
27160 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27170 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
27180 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
27190 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
271a0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
271b0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
271c0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
271d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
271e0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
271f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
27200 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
27210 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
27220 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
27230 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
27240 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
27250 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
27260 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
27270 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
27280 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
27290 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
272a0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
272b0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
272c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
272d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
272e0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
272f0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
27300 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27310 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27320 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
27330 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
27340 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
27350 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
27360 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
27370 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
27380 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27390 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
273a0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
273b0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
273c0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
273d0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
273e0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
273f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27400 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
27410 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
27420 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
27430 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27440 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
27450 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c  ar *zParam);.SQL
27460 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
27470 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
27480 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
27490 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
274a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
274b0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
274c0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
274d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51  sqlite3_int64 SQ
274e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
274f0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
27500 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
27510 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
27520 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
27530 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
27540 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
27550 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
27560 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
27570 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27580 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
27590 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
275a0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
275b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
275c0 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
275d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
275e0 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
275f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
27600 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
27610 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
27620 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
27630 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
27640 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
27650 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
27660 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
27670 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
27680 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
27690 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
276a0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
276b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
276c0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
276d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
276e0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
276f0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
27700 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
27710 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
27720 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
27730 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
27740 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
27750 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
27760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27770 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
27780 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
27790 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
277a0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
277b0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
277c0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
277d0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
277e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
277f0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27800 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27810 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27820 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
27830 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
27840 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
27850 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
27860 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
27870 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
27880 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
27890 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
278a0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
278b0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
278c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
278d0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
278e0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
278f0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
27900 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
27910 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27920 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
27930 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
27940 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27950 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
27960 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
27970 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27980 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27990 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
279a0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
279b0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
279c0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
279d0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
279e0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
279f0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
27a00 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
27a10 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
27a20 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
27a30 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
27a40 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
27a50 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
27a60 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
27a70 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
27a80 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
27a90 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
27aa0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
27ab0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
27ac0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
27ad0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
27ae0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
27af0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
27b00 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
27b10 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
27b20 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
27b30 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
27b40 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
27b50 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
27b60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27b70 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
27b80 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27b90 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
27ba0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27bb0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
27bc0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
27bd0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
27be0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
27bf0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
27c00 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
27c10 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
27c20 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
27c30 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
27c40 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
27c50 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
27c60 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
27c70 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
27c80 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
27c90 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
27ca0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
27cb0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
27cc0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
27cd0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
27ce0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
27cf0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
27d00 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
27d10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
27d20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
27d30 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
27d40 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
27d50 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
27d60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65  ALL sqlite3_exte
27d70 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
27d80 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
27d90 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
27da0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
27db0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
27dc0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
27dd0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
27de0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
27df0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
27e00 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
27e10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
27e20 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
27e30 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  LL sqlite3_errst
27e40 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
27e50 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
27e60 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
27e70 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
27e80 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
27e90 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
27ea0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
27eb0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
27ec0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
27ed0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
27ee0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
27ef0 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
27f00 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
27f10 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
27f20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
27f30 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
27f40 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
27f50 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
27f60 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
27f70 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
27f80 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
27f90 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
27fa0 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
27fb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
27fc0 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
27fd0 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
27fe0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
27ff0 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
28000 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
28010 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
28020 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
28030 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
28040 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
28050 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
28060 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
28070 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
28080 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
28090 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
280a0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
280b0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
280c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
280d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
280e0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
280f0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
28100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
28110 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
28120 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
28130 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
28140 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
28150 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
28160 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
28170 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
28180 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
28190 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
281a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
281b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
281c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
281d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
281e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
281f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
28200 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
28210 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
28220 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
28230 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
28240 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
28250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28260 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
28270 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28280 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
28290 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
282a0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
282b0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
282c0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
282d0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
282e0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
282f0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
28300 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
28310 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
28320 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
28330 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
28340 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
28350 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
28360 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
28370 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
28380 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
28390 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
283a0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
283b0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
283c0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
283d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
283e0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
283f0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
28400 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
28410 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
28420 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
28430 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
28440 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
28450 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
28460 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
28470 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
28480 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
28490 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
284a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
284b0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
284c0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
284d0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
284e0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
284f0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
28500 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
28510 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
28520 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
28530 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
28540 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
28550 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
28560 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
28570 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
28580 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
28590 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
285a0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
285b0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
285c0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
285d0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
285e0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
285f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
28600 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
28610 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
28620 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
28630 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
28640 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
28650 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
28660 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
28670 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
28680 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
28690 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
286a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
286b0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
286c0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
286d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
286e0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
286f0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
28700 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
28710 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
28720 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
28730 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
28740 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
28750 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
28760 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
28770 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
28780 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
28790 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
287a0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
287b0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
287c0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
287d0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
287e0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
287f0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
28800 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
28810 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
28820 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
28830 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
28840 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
28850 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
28860 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
28870 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
28880 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
28890 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
288a0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
288b0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
288c0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
288d0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
288e0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
288f0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
28900 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
28910 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
28920 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
28930 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
28940 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
28950 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
28960 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
28970 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
28980 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
28990 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
289a0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
289b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
289c0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
289d0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
289e0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
289f0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
28a00 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
28a10 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53  e releases..*/.S
28a20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
28a30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
28a40 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
28a50 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
28a60 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
28a70 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
28a80 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
28a90 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
28aa0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
28ab0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
28ac0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
28ad0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
28ae0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
28af0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
28b00 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
28b10 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
28b20 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
28b30 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
28b40 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
28b50 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
28b60 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
28b70 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
28b80 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
28b90 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
28ba0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
28bb0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
28bc0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
28bd0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
28be0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
28bf0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28c00 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
28c10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28c20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
28c30 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
28c40 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
28c50 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
28c60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
28c70 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
28c80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
28c90 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
28ca0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28cb0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
28cc0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
28cd0 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
28ce0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28cf0 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
28d00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
28d10 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
28d20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
28d30 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28d40 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
28d50 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
28d60 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
28d70 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
28d80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28d90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28da0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
28db0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
28dc0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
28dd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28de0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
28df0 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
28e00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
28e10 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
28e20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28e30 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
28e40 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
28e50 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
28e60 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28e70 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
28e80 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
28e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
28ea0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
28eb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28ec0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
28ed0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
28ee0 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
28ef0 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
28f00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28f10 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
28f20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
28f30 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
28f40 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
28f50 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
28f60 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
28f70 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
28f80 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
28f90 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
28fa0 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
28fb0 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
28fc0 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
28fd0 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
28fe0 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
28ff0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
29000 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
29010 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
29020 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
29030 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
29040 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29050 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
29060 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29070 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29080 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
29090 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
290a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
290b0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
290c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
290d0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
290e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
290f0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
29100 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
29110 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
29120 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
29130 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29140 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
29150 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
29160 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29170 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
29180 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29190 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
291a0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
291b0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
291c0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
291d0 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
291e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
291f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
29200 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
29210 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
29220 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
29230 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29240 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
29250 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
29260 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
29270 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
29280 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
29290 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
292a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
292b0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
292c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
292d0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
292e0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
292f0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
29300 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29310 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29320 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
29330 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29340 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
29350 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29360 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
29370 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
29380 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
29390 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
293a0 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
293b0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
293c0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
293d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
293e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
293f0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
29400 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
29410 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
29420 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
29430 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29440 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
29450 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
29460 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
29470 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
29480 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
29490 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
294a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
294b0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
294c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
294d0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
294e0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
294f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29500 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
29510 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
29520 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29530 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
29540 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
29550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29560 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29570 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
29580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29590 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
295a0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
295b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
295c0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
295d0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
295e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
295f0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29600 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
29610 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
29620 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
29630 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
29640 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
29650 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
29660 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
29670 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52  qlite3.** CONSTR
29680 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
29690 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  tmt.**.** To exe
296a0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
296b0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
296c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
296d0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
296e0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
296f0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
29700 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
29710 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
29720 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
29730 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29740 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
29750 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
29760 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
29770 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
29780 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
29790 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
297a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
297b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
297c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
297d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
297e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
297f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
29800 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
29810 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
29820 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
29830 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
29840 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
29850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
29860 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
29870 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
29880 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
29890 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
298a0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
298b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
298c0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
298d0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
298e0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
298f0 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  nt is negative, 
29900 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
29910 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
29920 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
29930 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
29940 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
29950 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e  n it is the.** n
29960 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72  umber of bytes r
29970 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
29980 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72  ^If nByte is zer
29990 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61  o, then no prepa
299a0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
299b0 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a   is generated..*
299c0 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  * If the caller 
299d0 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73  knows that the s
299e0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
299f0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
29a00 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  , then.** there 
29a10 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f  is a small perfo
29a20 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
29a30 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   to passing an n
29a40 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
29a50 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  hat.** is the nu
29a60 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
29a70 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
29a80 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
29a90 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
29aa0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
29ab0 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
29ac0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
29ad0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
29ae0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
29af0 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
29b00 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
29b10 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
29b20 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
29b30 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
29b40 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
29b50 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
29b60 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
29b70 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
29b80 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
29b90 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
29ba0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
29bb0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
29bc0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
29bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29be0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
29bf0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
29c00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
29c10 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
29c20 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
29c30 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
29c40 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
29c50 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
29c60 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
29c70 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
29c80 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
29c90 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
29ca0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
29cb0 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
29cc0 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
29cd0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
29ce0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
29cf0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
29d00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
29d10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
29d20 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
29d30 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
29d40 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
29d50 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
29d60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
29d70 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
29d80 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
29d90 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
29da0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
29db0 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
29dc0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
29dd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
29de0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29df0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
29e00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29e10 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
29e20 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
29e30 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
29e40 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
29e50 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
29e60 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
29e70 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
29e80 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
29e90 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
29ea0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
29eb0 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
29ec0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
29ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ee0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
29ef0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
29f00 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
29f10 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
29f20 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
29f30 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
29f40 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
29f50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29f60 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
29f70 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
29f80 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
29f90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
29fa0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
29fb0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
29fc0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
29fd0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
29fe0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
29ff0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
2a000 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
2a010 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2a020 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2a030 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
2a040 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
2a050 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
2a060 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
2a070 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
2a080 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
2a090 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
2a0a0 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
2a0b0 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
2a0c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
2a0d0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
2a0e0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
2a0f0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
2a100 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
2a110 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
2a120 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
2a130 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
2a140 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
2a150 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
2a160 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
2a170 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
2a180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2a190 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
2a1a0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
2a1b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2a1c0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
2a1d0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
2a1e0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
2a1f0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
2a200 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a210 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
2a220 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
2a230 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
2a240 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
2a250 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
2a260 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
2a270 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
2a280 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
2a290 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
2a2a0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
2a2b0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
2a2c0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2a2d0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2a2e0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
2a2f0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
2a300 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
2a310 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2a320 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2a330 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
2a340 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
2a350 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
2a360 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
2a370 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2a380 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
2a390 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
2a3a0 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
2a3b0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
2a3c0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
2a3d0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2a3e0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
2a3f0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
2a400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a410 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
2a420 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
2a430 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
2a440 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
2a450 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
2a460 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
2a470 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
2a480 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2a490 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
2a4a0 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
2a4b0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
2a4c0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
2a4d0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
2a4e0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a4f0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
2a500 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
2a510 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
2a520 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
2a530 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
2a540 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
2a550 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
2a560 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ol>.*/.SQLITE_A
2a570 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2a580 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72  DCALL sqlite3_pr
2a590 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2a5a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a5b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a5c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a5d0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2a5e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a5f0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2a600 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a620 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a630 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a640 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a650 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a660 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a670 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a680 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2a690 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a6a0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a6b0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a6c0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a6d0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2a6e0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2a6f0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2a700 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a710 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a720 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a730 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2a740 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a750 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2a760 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a780 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a790 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a7a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a7b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a7c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a7d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a7e0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2a7f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a800 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a810 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a820 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a830 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2a840 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2a850 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2a860 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a870 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2a880 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2a890 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2a8a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2a8b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2a8c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a8e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a8f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a900 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a910 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a920 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a930 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a940 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2a950 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a960 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a970 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a980 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a990 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2a9a0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2a9b0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
2a9c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a9d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a9e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a9f0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2aa00 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2aa10 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2aa20 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2aa30 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2aa40 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2aa50 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2aa60 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2aa70 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2aa80 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2aa90 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2aaa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2aab0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2aac0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2aad0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2aae0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
2aaf0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
2ab00 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
2ab10 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
2ab20 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2ab30 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2ab40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2ab50 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
2ab60 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
2ab70 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
2ab80 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2ab90 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2aba0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
2abb0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
2abc0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
2abd0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2abe0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2abf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ac00 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
2ac10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2ac20 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2ac30 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  LL sqlite3_sql(s
2ac40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2ac50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2ac60 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2ac70 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2ac80 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2ac90 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2aca0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2acb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2acc0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2acd0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2ace0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2acf0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2ad00 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2ad10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ad20 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2ad30 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2ad40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2ad50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2ad60 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2ad70 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2ad80 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2ad90 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2ada0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2adb0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2adc0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2add0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2ade0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2adf0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2ae00 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2ae10 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2ae20 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2ae30 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2ae40 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2ae50 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2ae60 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2ae70 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2ae80 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2ae90 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2aea0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2aeb0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2aec0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2aed0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2aee0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2aef0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2af00 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2af10 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2af20 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2af30 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2af40 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2af50 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2af60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2af70 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2af80 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2af90 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2afa0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2afb0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2afc0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2afd0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2afe0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2aff0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2b000 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2b010 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2b020 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2b030 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2b040 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2b050 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2b060 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2b070 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2b080 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2b090 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2b0a0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2b0b0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2b0c0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2b0d0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2b0e0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2b0f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2b100 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2b110 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2b120 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2b130 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2b140 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2b150 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2b160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2b170 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2b180 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2b190 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2b1a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b1b0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51  s on disk..*/.SQ
2b1c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b1d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b1e0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b1f0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2b200 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b210 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2b220 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2b230 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2b240 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2b250 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b260 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b270 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2b280 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b290 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2b2a0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2b2b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b2c0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2b2d0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2b2e0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2b2f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b300 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20  but has neither 
2b310 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2b320 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  n (returned.** [
2b330 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f  SQLITE_DONE] fro
2b340 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  m [sqlite3_step(
2b350 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e  S)]) nor.** been
2b360 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
2b370 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
2b380 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
2b390 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
2b3a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b3b0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
2b3c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
2b3d0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
2b3e0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
2b3f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
2b400 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
2b410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b420 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
2b430 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2b440 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2b450 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
2b460 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
2b470 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2b480 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
2b490 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
2b4a0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
2b4b0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
2b4c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b4d0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
2b4e0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
2b4f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
2b500 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
2b510 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
2b520 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
2b530 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
2b540 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
2b550 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
2b560 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
2b570 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
2b580 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
2b590 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
2b5a0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2b5b0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2b5c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ALL sqlite3_stmt
2b5d0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2b5e0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2b5f0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2b600 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2b610 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2b620 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2b630 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2b640 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b650 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2b660 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2b670 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b680 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2b690 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2b6a0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2b6b0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2b6c0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2b6d0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2b6e0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2b6f0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2b700 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2b710 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2b720 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2b730 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2b740 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2b750 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2b760 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2b770 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2b780 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2b790 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2b7a0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2b7b0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2b7c0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2b7d0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2b7e0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2b7f0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2b800 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2b810 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2b820 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2b830 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2b840 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2b850 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2b860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2b870 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2b880 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2b890 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2b8a0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2b8b0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2b8c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2b8d0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2b8e0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2b8f0 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2b900 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2b910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2b920 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2b930 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b940 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2b950 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2b960 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2b970 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2b980 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2b990 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2b9a0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2b9b0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2b9c0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2b9d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2b9e0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2b9f0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2ba00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2ba10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2ba20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2ba30 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2ba40 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2ba50 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2ba60 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2ba70 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2ba80 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2ba90 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2baa0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2bab0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2bac0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2bad0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2bae0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2baf0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2bb00 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2bb10 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2bb20 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2bb30 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2bb40 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2bb50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2bb60 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2bb70 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2bb80 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2bb90 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2bba0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2bbb0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2bbc0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2bbd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2bbe0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2bbf0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2bc00 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2bc10 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2bc20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2bc30 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2bc40 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2bc50 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2bc60 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2bc70 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2bc80 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2bc90 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2bca0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2bcb0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2bcc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2bcd0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2bce0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2bcf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bd00 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2bd10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2bd20 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2bd30 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2bd40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2bd50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2bd60 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2bd70 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
2bd80 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2bd90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2bda0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
2bdb0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
2bdc0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
2bdd0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
2bde0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
2bdf0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2be00 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
2be10 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2be20 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
2be30 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
2be40 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2be50 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2be60 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2be70 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2be80 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2be90 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2bea0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2beb0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2bec0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2bed0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2bee0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2bef0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2bf00 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2bf10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2bf20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bf30 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2bf40 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2bf50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bf60 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2bf70 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2bf80 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2bf90 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2bfa0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2bfb0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2bfc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2bfd0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2bfe0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2bff0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2c000 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2c010 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2c020 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2c030 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2c040 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2c050 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2c060 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2c070 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2c080 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2c090 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2c0a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2c0b0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2c0c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2c0d0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2c0e0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2c0f0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2c100 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2c110 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2c120 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2c130 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2c140 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2c150 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2c160 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c170 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2c180 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2c190 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c1b0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2c1c0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2c1d0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2c1e0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2c1f0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2c200 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2c210 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2c220 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2c230 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2c240 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2c250 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2c260 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2c270 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2c280 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2c290 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2c2a0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2c2b0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2c2c0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2c2d0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2c2e0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2c2f0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2c300 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2c310 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2c320 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2c330 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2c340 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2c350 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2c360 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2c370 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2c380 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2c390 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c3a0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2c3b0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2c3c0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2c3d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c3e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2c3f0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2c400 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2c410 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c420 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2c430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2c440 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2c450 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2c460 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2c470 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2c480 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2c490 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2c4a0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2c4b0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2c4c0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2c4d0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2c4e0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2c4f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2c500 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2c510 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2c520 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2c530 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2c540 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2c550 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2c560 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2c570 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2c580 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c590 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2c5a0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2c5b0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2c5c0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2c5d0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2c5e0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2c5f0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2c600 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2c610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2c620 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2c630 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2c640 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2c650 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2c660 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2c670 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2c680 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2c690 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2c6a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2c6b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2c6c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2c6d0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2c6e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c6f0 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2c700 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2c710 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2c720 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2c730 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2c740 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2c750 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2c760 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2c770 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2c780 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2c790 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2c7a0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2c7b0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2c7c0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2c7d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c7e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2c7f0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2c800 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2c810 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2c820 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2c830 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2c840 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2c850 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2c860 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2c870 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2c880 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2c890 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2c8a0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2c8b0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2c8c0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2c8d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2c8e0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2c8f0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2c900 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2c910 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c920 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2c930 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2c940 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2c950 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2c960 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2c970 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2c980 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2c990 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2c9a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c9b0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2c9c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2c9d0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c9e0 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2c9f0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2ca00 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2ca10 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2ca20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2ca30 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2ca40 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2ca50 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2ca60 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2ca70 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2ca80 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2ca90 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2caa0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2cab0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2cac0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2cad0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2cae0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2caf0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2cb00 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2cb10 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2cb20 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2cb30 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2cb40 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2cb50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2cb60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2cb70 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2cb80 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2cb90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2cba0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2cbb0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2cbc0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2cbd0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2cbe0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2cbf0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2cc00 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2cc10 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2cc20 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2cc30 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2cc40 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2cc50 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2cc60 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2cc70 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2cc80 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2cc90 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2cca0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2ccb0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2ccc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2ccd0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2cce0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2ccf0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2cd00 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2cd10 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2cd20 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2cd30 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2cd40 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2cd50 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2cd60 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2cd70 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2cd80 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2cd90 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2cda0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2cdb0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2cdc0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2cdd0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2cde0 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2cdf0 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2ce00 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2ce10 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2ce20 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2ce30 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2ce40 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2ce50 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2ce60 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2ce70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2ce80 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2ce90 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2cea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ceb0 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2cec0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2ced0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2cee0 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2cef0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2cf00 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2cf10 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2cf20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2cf30 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2cf40 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2cf50 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2cf60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2cf70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2cf80 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2cf90 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2cfa0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2cfb0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2cfc0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2cfd0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2cfe0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2cff0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2d000 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2d010 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2d020 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2d030 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2d040 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2d050 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2d060 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2d070 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2d080 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2d090 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2d0a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2d0b0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2d0c0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2d0d0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2d0e0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2d0f0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2d100 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2d110 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2d120 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2d130 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d140 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2d150 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2d160 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2d170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d180 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2d190 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d1a0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2d1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d1c0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2d1d0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2d1e0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2d1f0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2d200 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2d210 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2d220 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2d230 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2d240 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2d250 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2d260 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2d270 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2d280 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2d290 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2d2a0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2d2b0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2d2c0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2d2d0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2d2e0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2d2f0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2d300 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2d310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2d320 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2d330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2d340 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2d350 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2d360 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2d370 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2d380 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2d390 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2d3a0 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
2d3b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2d3c0 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
2d3d0 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
2d3e0 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
2d3f0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
2d400 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2d410 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
2d420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
2d430 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
2d440 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
2d450 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
2d460 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
2d470 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2d480 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
2d490 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
2d4a0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
2d4b0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2d4c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2d4d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2d4e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2d4f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d500 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
2d510 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d520 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2d530 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2d540 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d560 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2d570 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2d580 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2d590 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2d5a0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d5b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d5c0 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
2d5d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d5e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
2d5f0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2d600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d610 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2d620 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2d630 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d640 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2d650 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
2d660 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
2d670 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
2d680 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d690 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d6a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2d6b0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
2d6c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d6d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d6e0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
2d6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d700 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
2d710 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
2d720 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2d730 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  L sqlite3_bind_n
2d740 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2d750 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
2d760 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2d770 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2d780 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
2d790 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
2d7a0 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
2d7b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2d7c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2d7d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d7e0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
2d7f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d800 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2d810 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2d820 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2d830 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2d840 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2d850 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2d860 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d870 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2d880 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2d890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d8a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2d8b0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2d8c0 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45  ncoding);.SQLITE
2d8d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2d8e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d8f0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2d900 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2d910 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2d920 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2d930 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d940 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d950 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2d960 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2d970 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t n);.SQLITE_API
2d980 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d990 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d9a0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
2d9b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d9c0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
2d9d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d9e0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2d9f0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2da00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2da10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2da20 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2da30 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2da40 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2da50 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2da60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2da70 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2da80 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2da90 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2daa0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2dab0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2dac0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2dad0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2dae0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2daf0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2db00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2db10 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2db20 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2db30 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2db40 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2db50 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2db60 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2db70 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2db80 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2db90 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2dba0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2dbb0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2dbc0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2dbd0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2dbe0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2dbf0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2dc00 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2dc10 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2dc20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2dc30 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2dc40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2dc50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2dc60 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2dc70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2dc80 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2dc90 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2dca0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2dcb0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2dcc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2dcd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2dce0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2dcf0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2dd00 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2dd10 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2dd20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2dd30 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ter.** METHOD: s
2dd40 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2dd50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2dd60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2dd70 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2dd80 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2dd90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2dda0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2ddb0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2ddc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2ddd0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2dde0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2ddf0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2de00 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2de10 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2de20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2de30 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2de40 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2de50 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2de60 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2de70 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2de80 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2de90 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2dea0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2deb0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2dec0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2ded0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2dee0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2def0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2df00 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2df10 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2df20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2df30 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2df40 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2df50 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2df60 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2df70 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2df80 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2df90 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2dfa0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2dfb0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2dfc0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2dfd0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2dfe0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2dff0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2e000 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2e010 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2e020 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2e030 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2e040 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2e050 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2e060 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2e070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e080 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2e090 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e0a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2e0b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2e0c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2e0d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2e0e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e0f0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2e100 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2e110 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e120 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2e130 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2e140 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2e150 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e160 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2e170 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2e180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e190 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2e1a0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2e1b0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
2e1c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e1d0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2e1e0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2e1f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2e200 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2e210 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2e220 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2e230 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2e240 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2e250 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2e260 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2e270 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2e280 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2e290 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2e2a0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2e2b0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2e2c0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2e2d0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2e2e0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2e2f0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2e300 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2e310 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2e320 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2e330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e340 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2e350 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e360 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2e370 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2e380 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e390 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2e3a0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2e3b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e3c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e3d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2e3e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2e3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e400 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2e410 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2e420 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2e430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2e440 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2e450 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2e460 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2e470 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e480 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2e490 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2e4a0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2e4b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2e4c0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2e4d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2e4e0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2e4f0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2e500 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2e510 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2e520 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2e530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2e540 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
2e550 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2e560 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e570 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2e580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e5a0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2e5b0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2e5c0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2e5d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e5e0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2e5f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2e600 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2e610 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2e620 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2e630 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2e640 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e650 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2e660 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2e670 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2e680 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2e690 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2e6a0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2e6b0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2e6c0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2e6d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2e6e0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2e6f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2e700 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2e710 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e720 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2e730 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2e740 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2e750 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2e770 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2e780 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2e790 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2e7a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2e7b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2e7c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2e7d0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2e7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2e7f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2e800 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2e810 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2e820 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2e830 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2e840 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2e850 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2e860 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2e870 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2e880 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2e890 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2e8a0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2e8b0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2e8c0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2e8d0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2e8e0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2e8f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2e900 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2e910 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2e920 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2e930 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2e940 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2e950 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2e960 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2e970 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2e980 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2e990 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2e9a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e9b0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2e9c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2e9d0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2e9e0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2e9f0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2ea00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2ea10 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2ea20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2ea30 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2ea40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2ea50 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2ea60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ea70 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2ea80 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2ea90 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2eaa0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2eab0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2eac0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2ead0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2eae0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2eaf0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2eb00 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2eb10 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2eb20 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2eb30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2eb40 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2eb50 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2eb60 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2eb70 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2eb80 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2eb90 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2eba0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2ebb0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2ebc0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2ebd0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2ebe0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2ebf0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2ec00 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2ec10 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2ec20 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2ec30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2ec40 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2ec50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2ec60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ec70 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
2ec80 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2ec90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2eca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ecb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ecc0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2ecd0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2ece0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2ecf0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2ed00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2ed10 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2ed20 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2ed30 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2ed40 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2ed50 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2ed60 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2ed70 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2ed80 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2ed90 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2eda0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2edb0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2edc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2edd0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2ede0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2edf0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2ee00 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2ee10 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2ee20 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2ee30 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2ee40 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2ee50 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2ee60 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2ee70 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2ee80 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2ee90 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2eea0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2eeb0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2eec0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2eed0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2eee0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2eef0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2ef00 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2ef10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ef20 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2ef30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2ef40 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2ef50 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2ef60 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2ef70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ef80 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2ef90 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2efa0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2efb0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2efc0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2efd0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2efe0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2eff0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2f000 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2f010 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2f020 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2f030 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2f040 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2f050 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f060 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2f070 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2f080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f090 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2f0a0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2f0b0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2f0c0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2f0d0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2f0e0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2f0f0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2f100 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2f110 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2f120 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2f130 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2f140 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2f150 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2f160 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2f170 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2f180 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2f190 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2f1a0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2f1b0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2f1c0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2f1d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2f1e0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2f1f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2f200 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2f210 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2f220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2f230 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2f240 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2f250 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2f260 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2f270 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2f280 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2f290 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2f2a0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2f2b0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2f2c0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2f2d0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2f2e0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2f2f0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2f300 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2f310 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2f320 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2f330 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2f340 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2f350 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2f360 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2f370 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2f380 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2f390 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2f3a0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2f3b0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2f3c0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2f3d0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2f3e0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2f3f0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2f400 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2f410 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2f420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f430 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2f440 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2f450 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f460 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2f470 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2f480 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2f490 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2f4a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f4b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2f4c0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2f4d0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2f4e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2f4f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f500 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2f510 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2f520 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2f530 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f540 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
2f550 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2f560 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2f570 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f580 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2f590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f5a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f5b0 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2f5c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2f5d0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2f5e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2f5f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2f600 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2f610 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2f620 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f630 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2f640 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f650 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f660 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2f670 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2f680 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2f690 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f6a0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2f6b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2f6c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2f6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2f6e0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2f6f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2f700 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2f710 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2f720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f730 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2f740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f760 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2f770 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2f780 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2f790 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f7a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2f7b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2f7c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f7d0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2f7e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2f7f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2f800 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2f810 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2f820 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2f830 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2f840 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2f850 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2f860 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2f870 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2f880 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2f890 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2f8a0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2f8b0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2f8c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2f8d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2f8e0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2f8f0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2f900 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2f910 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2f920 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2f930 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2f940 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2f950 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2f960 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2f970 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2f980 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2f990 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2f9a0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2f9b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2f9c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2f9d0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2f9e0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2f9f0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2fa00 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2fa10 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2fa20 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2fa30 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2fa40 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2fa50 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2fa60 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2fa70 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2fa80 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2fa90 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2faa0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2fab0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2fac0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2fad0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2fae0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2faf0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2fb00 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2fb10 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2fb20 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2fb30 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2fb40 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2fb50 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2fb60 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2fb70 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2fb80 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2fb90 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2fba0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2fbb0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2fbc0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2fbd0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2fbe0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2fbf0 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
2fc00 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2fc10 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2fc20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2fc30 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2fc40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2fc50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2fc60 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2fc70 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2fc80 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2fc90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2fca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fcb0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2fcc0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2fcd0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2fce0 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
2fcf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fd00 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2fd10 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2fd20 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2fd30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2fd40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2fd50 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2fd60 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2fd70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2fd80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2fd90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2fda0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2fdb0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2fdc0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2fdd0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2fde0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2fdf0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2fe00 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2fe10 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2fe20 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2fe30 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2fe40 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2fe50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2fe60 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2fe70 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2fe80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2fe90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2fea0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2feb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2fec0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2fed0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2fee0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2fef0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2ff00 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2ff10 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2ff20 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2ff30 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2ff40 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2ff50 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2ff60 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2ff70 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2ff80 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2ff90 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2ffa0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2ffb0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2ffc0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2ffd0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2ffe0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2fff0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
30000 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
30010 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
30020 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
30030 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
30040 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
30050 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
30060 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
30070 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
30080 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
30090 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
300a0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
300b0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
300c0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
300d0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
300e0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
300f0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
30100 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
30110 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
30120 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
30130 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
30140 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
30150 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
30160 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
30170 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
30180 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
30190 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
301a0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
301b0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
301c0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
301d0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
301e0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
301f0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
30200 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
30210 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
30220 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
30230 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
30240 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
30250 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
30260 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
30270 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
30280 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
30290 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
302a0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
302b0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
302c0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
302d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
302e0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
302f0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
30300 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
30310 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
30320 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
30330 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
30340 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
30350 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
30360 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
30370 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
30380 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
30390 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
303a0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
303b0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
303c0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
303d0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
303e0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
303f0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
30400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
30410 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
30420 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
30430 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
30440 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
30450 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
30460 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
30470 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
30480 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
30490 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
304a0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
304b0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
304c0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
304d0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
304e0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
304f0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
30500 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
30510 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
30520 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
30530 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
30540 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
30550 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
30560 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
30570 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
30580 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
30590 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
305a0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
305b0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
305c0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
305d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
305e0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
305f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
30600 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
30610 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
30620 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
30630 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
30640 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
30650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
30660 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
30670 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
30680 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
30690 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
306a0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
306b0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
306c0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
306d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
306e0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
306f0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
30700 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
30710 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
30720 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
30730 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
30740 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
30750 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
30760 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
30770 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
30780 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
30790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
307a0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
307b0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
307c0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
307d0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
307e0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
307f0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
30800 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
30810 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
30820 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
30830 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30840 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
30850 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
30860 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
30870 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
30880 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
30890 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
308a0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
308b0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
308c0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
308d0 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
308e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
308f0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
30900 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30910 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
30920 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30930 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
30940 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
30950 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
30960 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
30970 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
30980 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
30990 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
309a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
309b0 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
309c0 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
309d0 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
309e0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
309f0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
30a00 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
30a10 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
30a20 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
30a30 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
30a40 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
30a50 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
30a60 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
30a70 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
30a80 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
30a90 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
30aa0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
30ab0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
30ac0 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
30ad0 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
30ae0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
30af0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
30b00 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
30b10 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
30b20 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
30b30 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
30b40 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
30b50 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
30b60 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
30b70 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
30b80 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
30b90 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
30ba0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
30bb0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
30bc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30bd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
30be0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
30bf0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
30c00 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
30c10 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
30c20 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
30c30 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
30c40 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
30c50 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
30c60 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
30c70 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
30c80 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
30c90 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
30ca0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
30cb0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
30cc0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
30cd0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
30ce0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30cf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30d00 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
30d10 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
30d20 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
30d30 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
30d40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30d50 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
30d60 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
30d70 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
30d80 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
30d90 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
30da0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
30db0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
30dc0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
30dd0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
30de0 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
30df0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
30e00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74  DCALL sqlite3_st
30e10 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
30e20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30e30 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
30e40 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
30e50 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
30e60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30e70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30e80 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
30e90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30ea0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
30eb0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
30ec0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
30ed0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
30ee0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
30ef0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
30f00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30f10 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
30f20 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
30f30 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
30f40 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
30f50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30f60 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
30f70 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
30f80 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
30f90 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
30fa0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
30fb0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
30fc0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30fd0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
30fe0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
30ff0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
31000 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31010 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
31020 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
31030 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
31040 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
31050 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
31060 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
31070 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
31080 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31090 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
310a0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
310b0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
310c0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
310d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
310e0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
310f0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
31100 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
31110 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
31120 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
31130 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
31140 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
31150 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
31160 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
31170 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
31180 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
31190 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
311a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
311b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
311c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
311d0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
311e0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
311f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
31200 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
31210 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
31220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
31230 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
31240 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
31250 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
31260 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
31270 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
31280 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
31290 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
312a0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
312b0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
312c0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
312d0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
312e0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
312f0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
31300 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
31310 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
31320 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
31330 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
31340 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
31350 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
31360 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
31370 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
31380 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
31390 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
313a0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
313b0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
313c0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
313d0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
313e0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
313f0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
31400 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
31410 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
31420 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
31430 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
31440 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
31450 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
31460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
31470 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
31480 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
31490 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
314a0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
314b0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
314c0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
314d0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
314e0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
314f0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
31500 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31510 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
31520 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
31530 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
31540 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
31550 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31560 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31570 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
31580 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
31590 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
315a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
315b0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
315c0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
315d0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
315e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
315f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
31600 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
31610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31620 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
31630 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
31640 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
31650 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
31660 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
31670 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
31680 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
31690 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
316a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
316b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
316c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
316d0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
316e0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
316f0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
31700 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
31710 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31720 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
31730 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
31740 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
31750 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
31760 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
31770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
31780 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
31790 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
317a0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
317b0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
317c0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
317d0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
317e0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
317f0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
31800 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
31810 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
31820 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
31830 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
31840 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
31850 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
31860 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
31870 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31880 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
31890 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
318a0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
318b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
318c0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
318d0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
318e0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
318f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
31900 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
31910 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
31920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
31930 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
31940 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
31950 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
31960 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
31970 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
31980 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
31990 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
319a0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
319b0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
319c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
319d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
319e0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
319f0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
31a00 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
31a10 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
31a20 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
31a30 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
31a40 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
31a50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31a60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31a70 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
31a80 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
31a90 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
31aa0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
31ab0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
31ac0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
31ad0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
31ae0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
31af0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
31b00 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
31b10 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
31b20 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
31b30 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
31b40 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
31b50 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
31b60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
31b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b80 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
31b90 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
31ba0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
31bb0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
31bc0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
31bd0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
31be0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
31bf0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
31c00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
31c10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
31c20 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
31c30 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
31c40 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
31c50 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
31c60 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
31c70 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
31c80 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
31c90 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
31ca0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31cb0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
31cc0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
31cd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
31ce0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
31cf0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
31d00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31d10 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
31d20 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
31d30 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31d40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
31d50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
31d60 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
31d70 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
31d80 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
31d90 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
31da0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31db0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31dc0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
31dd0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
31de0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31df0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
31e00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
31e10 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
31e20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
31e30 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
31e40 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
31e50 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31e60 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
31e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31e80 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
31e90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31ea0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
31eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
31ec0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
31ed0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
31ee0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
31ef0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
31f00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
31f10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
31f20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
31f30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
31f40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
31f50 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
31f60 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
31f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
31f80 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
31f90 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
31fa0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
31fb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31fc0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
31fd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31fe0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
31ff0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32000 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
32010 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
32020 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
32030 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
32040 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
32050 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
32060 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
32070 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
32080 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
32090 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
320a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
320b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
320c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
320d0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
320e0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
320f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32100 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
32110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32120 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
32130 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
32140 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
32150 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
32160 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
32170 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
32180 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
32190 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
321a0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
321b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
321c0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
321d0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
321e0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
321f0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
32200 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
32210 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
32220 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
32240 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
32250 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
32260 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
32270 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
32280 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
32290 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
322a0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
322b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
322c0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
322d0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
322e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
322f0 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c  .** <b>Warning:<
32300 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  /b> ^The object 
32310 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
32320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
32330 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
32340 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32350 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32360 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72  .  In a multithr
32370 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e  eaded environmen
32380 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65  t,.** an unprote
32390 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
323a0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e  ue object may on
323b0 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c  ly be used safel
323c0 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  y with.** [sqlit
323d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
323e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
323f0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
32400 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
32410 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32420 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
32430 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
32440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
32450 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
32460 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
32470 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
32480 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
32490 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
324a0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
324b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
324c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
324d0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
324e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
324f0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a  not threadsafe..
32500 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32510 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
32520 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32530 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
32540 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
32550 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
32560 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
32570 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
32580 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
32590 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
325a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
325b0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
325c0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
325d0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
325e0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
325f0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
32600 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
32610 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
32620 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
32630 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
32640 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
32650 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
32660 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
32670 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
32680 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
32690 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
326a0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
326b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
326c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
326d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
326e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
326f0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
32700 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
32710 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
32720 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
32730 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
32740 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
32750 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
32760 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32770 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
32780 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
32790 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
327a0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
327b0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
327c0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
327d0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
327e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
327f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
32800 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
32810 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
32820 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
32830 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
32840 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32850 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
32860 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
32870 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
32880 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
32890 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
328a0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
328b0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
328c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
328d0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
328e0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
328f0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
32900 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32910 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
32920 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
32930 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
32940 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
32950 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
32960 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32970 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
32980 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32990 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
329a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
329b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
329c0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
329d0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
329e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
329f0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
32a00 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
32a10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
32a20 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
32a30 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
32a40 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
32a50 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
32a60 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
32a70 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
32a80 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
32a90 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
32aa0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
32ab0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
32ac0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
32ad0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
32ae0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
32af0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
32b00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
32b10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32b20 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
32b30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32b40 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
32b50 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
32b60 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
32b70 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
32b80 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
32b90 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
32ba0 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
32bb0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
32bc0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32bd0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
32be0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32bf0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
32c00 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
32c10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
32c20 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
32c30 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
32c40 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
32c50 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
32c60 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
32c70 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
32c80 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
32c90 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
32ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32cb0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
32cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32cd0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
32ce0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
32cf0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
32d00 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
32d10 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
32d20 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32d30 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
32d40 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
32d50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32d60 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32d80 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
32d90 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
32da0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
32db0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
32dc0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
32dd0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
32de0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
32df0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
32e00 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
32e10 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
32e20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
32e30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
32e40 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
32e50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
32e60 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
32e70 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
32e80 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
32e90 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
32ea0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
32eb0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
32ec0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
32ed0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
32ee0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
32ef0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
32f00 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
32f10 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
32f20 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
32f30 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
32f40 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
32f50 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
32f60 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
32f70 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
32f80 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
32f90 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
32fa0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
32fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32fc0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
32fd0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32fe0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
32ff0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
33000 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
33010 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
33020 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
33030 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
33040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33050 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
33060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33070 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
33080 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
33090 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
330a0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
330b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
330c0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
330d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
330e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
330f0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
33100 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
33110 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
33120 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
33130 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
33140 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33150 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
33160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33170 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
33180 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
33190 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
331a0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
331b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
331c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
331d0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
331e0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
331f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33200 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
33210 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
33220 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33230 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
33240 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33250 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
33260 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
33270 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
33280 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
33290 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
332a0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
332b0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
332c0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
332d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
332e0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
332f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33300 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
33310 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
33320 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
33330 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
33340 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
33350 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
33360 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73  em>not</em> pass
33370 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
33380 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
33390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
333a0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
333b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
333c0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
333d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
333e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
333f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
33400 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
33410 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
33420 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
33430 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
33440 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
33450 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
33460 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
33470 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
33480 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
33490 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
334a0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
334b0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
334c0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
334d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
334e0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
334f0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
33500 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
33510 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
33520 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
33530 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33540 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
33550 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33560 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33570 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33590 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
335a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
335b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
335c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
335d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
335e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
335f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
33600 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53  ITE_API double S
33610 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33630 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
33640 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33650 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
33660 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
33680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33690 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
336a0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
336b0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
336c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
336d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
336e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
336f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
33700 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
33710 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33730 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
33740 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
33750 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
33760 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
33770 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33780 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
33790 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
337a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
337b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
337c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
337d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
337e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
337f0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
33800 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f  3_value *SQLITE_
33810 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33820 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
33830 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33840 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
33850 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
33860 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
33870 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
33880 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
33890 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
338a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
338b0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
338c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
338d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
338e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
338f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33900 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
33910 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
33920 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
33930 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
33940 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
33950 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
33960 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
33970 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
33980 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
33990 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
339a0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
339b0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
339c0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
339d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
339e0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
339f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
33a00 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
33a10 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
33a20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
33a30 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
33a40 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
33a50 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
33a60 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
33a70 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
33a80 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
33a90 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
33aa0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
33ab0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
33ac0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
33ad0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
33ae0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
33af0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
33b00 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
33b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33b20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
33b30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
33b40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
33b50 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
33b60 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
33b70 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
33b80 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
33b90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
33ba0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
33bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
33bc0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
33bd0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
33be0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33bf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
33c00 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
33c10 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
33c20 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
33c30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33c40 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
33c50 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
33c60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
33c70 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
33c80 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
33c90 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
33ca0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
33cb0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
33cc0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
33cd0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
33ce0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
33cf0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
33d00 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
33d10 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
33d20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
33d30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33d40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
33d60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
33d70 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
33d80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
33d90 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54  nt Object.** MET
33da0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
33db0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
33dc0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
33dd0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
33de0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
33df0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
33e00 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
33e10 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
33e20 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
33e30 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
33e40 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
33e50 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
33e60 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
33e70 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
33e80 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
33e90 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
33ea0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
33eb0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
33ec0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
33ed0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
33ee0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
33ef0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
33f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
33f10 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
33f20 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
33f30 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
33f40 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
33f50 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
33f60 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
33f70 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
33f80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
33f90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
33fa0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
33fb0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
33fc0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
33fd0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
33fe0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
33ff0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
34000 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
34010 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
34020 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
34030 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
34040 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
34050 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
34060 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
34070 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
34080 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
34090 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
340a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
340b0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
340c0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
340d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
340e0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
340f0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
34100 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
34110 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
34120 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
34130 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
34140 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
34150 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
34160 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
34170 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
34180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34190 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
341a0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
341b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65  ALL sqlite3_rese
341c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
341d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
341e0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
341f0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
34200 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
34210 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
34220 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34230 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
34240 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34250 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34260 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
34270 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34280 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34290 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
342a0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
342b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
342c0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
342d0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
342e0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
342f0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
34300 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
34310 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34320 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34330 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
34340 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
34350 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34360 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
34370 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
34380 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
34390 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
343a0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
343b0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
343c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
343d0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
343e0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
343f0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
34400 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
34410 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
34420 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
34430 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
34440 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34450 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
34460 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
34470 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
34480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34490 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
344a0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
344b0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
344c0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
344d0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
344e0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
344f0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
34500 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
34510 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34520 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
34530 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
34540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34550 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
34560 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
34570 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
34580 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
34590 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
345a0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
345b0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
345c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
345d0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
345e0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
345f0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
34600 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
34610 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
34620 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
34630 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
34640 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
34650 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
34660 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
34670 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
34680 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
34690 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
346a0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
346b0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
346c0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
346d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
346e0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
346f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
34700 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
34710 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
34720 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
34730 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
34740 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
34750 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
34760 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
34770 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
34780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34790 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
347a0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
347b0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
347c0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
347d0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
347e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
347f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
34800 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
34810 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
34820 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
34830 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
34840 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
34850 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
34860 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
34870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
34880 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
34890 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
348a0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
348b0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
348c0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
348d0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
348e0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
348f0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
34900 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
34910 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
34920 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
34930 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
34940 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34950 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
34960 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
34970 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
34980 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
34990 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
349a0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
349b0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
349c0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
349d0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
349e0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
349f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
34a00 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
34a10 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
34a20 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
34a30 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
34a40 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
34a50 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
34a60 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
34a70 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
34a80 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
34a90 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
34aa0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
34ab0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
34ac0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
34ad0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
34ae0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
34af0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34b00 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
34b10 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
34b20 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
34b30 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
34b40 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
34b50 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
34b60 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
34b70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
34b80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
34b90 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
34ba0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
34bb0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
34bc0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
34bd0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
34be0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
34bf0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
34c00 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
34c10 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
34c20 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
34c30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
34c40 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
34c50 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
34c60 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
34c70 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
34c80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
34c90 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
34ca0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
34cb0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
34cc0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
34cd0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
34ce0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
34cf0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
34d00 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
34d10 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
34d20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
34d30 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
34d40 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
34d50 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
34d60 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
34d70 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
34d80 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
34d90 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
34da0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
34db0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34dc0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
34dd0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
34de0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
34df0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
34e00 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
34e10 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
34e20 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
34e30 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
34e40 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
34e50 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
34e60 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
34e70 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
34e80 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
34e90 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
34ea0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
34eb0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
34ec0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
34ed0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
34ee0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
34ef0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
34f00 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
34f10 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
34f20 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
34f30 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
34f40 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
34f50 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
34f60 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
34f70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34f80 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
34f90 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
34fa0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
34fb0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
34fc0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
34fd0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
34fe0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
34ff0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
35000 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
35010 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
35020 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
35030 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
35040 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
35050 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35060 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
35070 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
35080 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
35090 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
350a0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
350b0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
350c0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
350d0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
350e0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
350f0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
35100 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
35110 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
35120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35130 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
35140 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
35150 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
35160 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
35170 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35180 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
35190 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
351a0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
351b0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
351c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
351d0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
351e0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
351f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
35200 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35210 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35220 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35230 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
35240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35250 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35260 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
35270 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
35280 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
35290 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
352a0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
352b0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
352c0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
352d0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
352e0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
352f0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
35300 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
35310 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
35320 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35330 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
35340 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
35350 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
35360 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
35370 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
35380 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
35390 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
353a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
353b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
353c0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
353d0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
353e0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
353f0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35410 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
35420 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
35430 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35440 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35450 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
35460 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
35470 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
35480 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
35490 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
354a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
354b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
354c0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
354d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
354e0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
354f0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
35500 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
35510 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
35520 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35530 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
35540 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
35550 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
35560 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
35570 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
35580 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
35590 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
355a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
355b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
355c0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
355d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
355e0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
355f0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
35600 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
35610 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35620 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
35630 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
35640 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35650 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
35660 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
35670 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
35680 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
35690 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
356a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
356b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
356c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
356d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
356e0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
356f0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35700 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35710 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35720 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35730 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35740 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35750 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35760 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35770 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
35780 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35790 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
357a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
357b0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
357c0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
357d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
357e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
357f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35800 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
35810 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
35820 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
35830 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
35840 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
35850 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
35860 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
35870 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35880 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35890 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
358a0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
358b0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
358c0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
358d0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
358e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
358f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
35900 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
35910 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35920 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
35930 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
35940 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
35950 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
35960 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
35970 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
35980 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
35990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
359a0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
359b0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
359c0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
359d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
359e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
359f0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
35a00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35a10 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
35a20 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
35a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
35a40 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
35a50 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
35a60 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
35a70 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
35a80 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
35a90 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
35aa0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
35ab0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
35ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
35ad0 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
35ae0 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
35af0 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
35b00 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
35b10 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
35b20 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
35b30 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
35b40 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
35b50 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
35b60 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
35b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35b80 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
35b90 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
35ba0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
35bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
35bc0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
35bd0 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
35be0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35bf0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
35c00 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
35c10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35c20 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
35c30 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
35c40 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
35c50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
35c60 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
35c70 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
35c80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
35c90 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
35ca0 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
35cb0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
35cc0 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
35cd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35ce0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35cf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35d00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
35d10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35d20 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
35d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
35d40 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
35d50 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
35d60 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
35d70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
35d80 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
35d90 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
35da0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
35db0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
35dc0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
35dd0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
35de0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
35df0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
35e00 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
35e10 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
35e20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
35e30 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
35e40 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
35e50 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
35e60 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72  ions.  To encour
35e70 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  age programmers 
35e80 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73  to avoid.** thes
35e90 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
35ea0 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e  will not explain
35eb0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
35ec0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
35ed0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
35ee0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
35ef0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
35f00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
35f10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
35f20 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
35f30 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
35f40 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
35f50 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
35f60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
35f70 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
35f80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
35f90 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
35fa0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
35fb0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
35fc0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
35fd0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
35fe0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
35ff0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
36000 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36010 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
36020 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f  CALL sqlite3_glo
36030 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
36040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
36050 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
36060 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
36070 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65  ALL sqlite3_thre
36080 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
36090 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
360a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
360b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
360c0 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
360d0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
360e0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
360f0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
36100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
36110 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
36120 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
36130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
36140 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65  aining SQL Value
36150 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
36160 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
36170 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
36180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
36190 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
361a0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
361b0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
361c0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
361d0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
361e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
361f0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
36200 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
36210 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  gate.  .**.** Th
36220 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
36230 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
36240 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
36250 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
36260 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
36270 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36280 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
36290 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
362a0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
362b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
362c0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
362d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
362e0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
362f0 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
36300 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
36310 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
36320 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
36330 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
36340 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36350 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
36360 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
36370 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
36380 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
36390 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
363a0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
363b0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
363c0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
363d0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
363e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
363f0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
36400 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
36410 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
36420 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36430 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
36440 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
36450 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
36460 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
36470 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36480 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
36490 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
364a0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
364b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
364c0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
364d0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
364e0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
364f0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
36500 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
36510 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
36520 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
36530 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36540 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
36550 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
36560 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
36570 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
36580 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
36590 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
365a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
365b0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
365c0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
365d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
365e0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
365f0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
36600 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
36610 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
36620 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
36630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
36640 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
36650 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
36660 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
36670 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
36680 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
36690 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
366a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
366b0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
366c0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
366d0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
366e0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
366f0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
36700 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
36710 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
36720 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
36730 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
36740 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
36750 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
36760 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
36770 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
36780 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
36790 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
367a0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
367b0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
367c0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
367d0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
367e0 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
367f0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
36800 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
36810 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
36820 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36830 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
36840 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
36850 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
36860 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
36870 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
36880 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
36890 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
368a0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
368b0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
368c0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
368d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
368e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
368f0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
36900 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
36910 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
36920 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
36930 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
36940 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
36950 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
36960 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36970 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
36980 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
36990 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
369a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
369b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
369c0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
369d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
369e0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
369f0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
36a00 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
36a10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36a20 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
36a30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36a40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
36a50 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36a60 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
36a70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
36a80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
36a90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36aa0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36ab0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36ac0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36ad0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
36af0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
36b00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36b10 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f  I double SQLITE_
36b20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36b30 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
36b40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36b50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
36b60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36b70 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
36b80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
36b90 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
36ba0 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  3_int64 SQLITE_S
36bb0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
36bc0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
36bd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36be0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
36bf0 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49  igned char *SQLI
36c00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36c10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
36c20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
36c30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
36c40 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
36c50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36c60 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
36c70 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36c80 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
36c90 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
36ca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
36cb0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
36cc0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
36cd0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
36ce0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36d00 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
36d10 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36d20 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
36d30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36d40 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
36d50 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
36d60 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
36d70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
36d80 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
36d90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
36da0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36db0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
36dc0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
36dd0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
36de0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
36df0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
36e00 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  e(V) function re
36e10 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70  turns the subtyp
36e20 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70  e for.** an [app
36e30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36e40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61   SQL function] a
36e50 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20  rgument V.  The 
36e60 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72  subtype.** infor
36e70 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  mation can be us
36e80 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d  ed to pass a lim
36e90 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63  ited amount of c
36ea0 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f  ontext from.** o
36eb0 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ne SQL function 
36ec0 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65  to another.  Use
36ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
36ee0 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a  sult_subtype()].
36ef0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65  ** routine to se
36f00 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  t the subtype fo
36f10 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  r the return val
36f20 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e  ue of an SQL fun
36f30 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ction..**.** SQL
36f40 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65  ite makes no use
36f50 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65   of subtype itse
36f60 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70  lf.  It merely p
36f70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70  asses the subtyp
36f80 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65  e.** from the re
36f90 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70  sult of one [app
36fa0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36fb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69   SQL function] i
36fc0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  nto the.** input
36fd0 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a   of another..*/.
36fe0 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73 69 67  SQLITE_API unsig
36ff0 6e 65 64 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  ned int SQLITE_S
37000 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
37010 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c  alue_subtype(sql
37020 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
37040 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c  opy And Free SQL
37050 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
37060 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
37070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37080 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29  te3_value_dup(V)
37090 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
370a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
370b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
370c0 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72  * object D and r
370d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
370e0 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20   to that copy.  
370f0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  ^The [sqlite3_va
37100 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a  lue] returned.**
37110 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64   is a [protected
37120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37130 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74  object even if t
37140 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e  he input is not.
37150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37160 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
37170 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37180 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c  NULL if V is NUL
37190 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d  L or if a.** mem
371a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
371b0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ails..**.** ^The
371c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
371d0 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63 65  ree(V) interface
371e0 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74   frees an [sqlit
371f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
37200 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
37210 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
37220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37230 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20  )].  ^If V is a 
37240 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
37250 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  then sqlite3_val
37260 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20  ue_free(V) is a 
37270 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
37280 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
37290 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
372a0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  L sqlite3_value 
372b0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
372c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
372d0 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  p(const sqlite3_
372e0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
372f0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
37300 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 53 51 4c  IMENTAL void SQL
37310 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37320 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
37330 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37350 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
37360 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
37370 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
37380 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37390 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
373a0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
373b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
373c0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
373d0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
373e0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
373f0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
37400 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
37410 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
37420 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37430 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
37440 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
37450 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
37460 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37470 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
37480 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
37490 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
374a0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
374b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
374c0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
374d0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
374e0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
374f0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
37500 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37510 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
37520 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
37530 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
37540 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
37550 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
37560 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
37570 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37580 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
37590 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
375a0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
375b0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
375c0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
375d0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
375e0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
375f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37600 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
37610 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
37620 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
37630 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
37640 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
37650 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
37660 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37670 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
37680 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
37690 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
376a0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
376b0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
376c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
376d0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
376e0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
376f0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
37700 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
37710 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
37720 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37730 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
37740 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
37750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
37760 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
37770 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
37780 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
37790 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
377a0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
377b0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
377c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
377d0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
377e0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
377f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37800 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
37810 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
37820 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
37830 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
37840 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
37850 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
37860 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
37870 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
37880 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37890 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
378a0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
378b0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
378c0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
378d0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
378e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
378f0 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
37900 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
37910 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
37920 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
37930 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
37940 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37950 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
37960 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
37970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
37980 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
37990 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
379a0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
379b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
379c0 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
379d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
379e0 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
379f0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
37a00 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
37a10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
37a20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
37a30 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
37a40 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
37a50 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
37a60 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
37a70 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
37a80 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
37a90 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37aa0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
37ab0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
37ac0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
37ad0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
37ae0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
37af0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
37b00 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
37b10 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
37b20 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
37b30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
37b40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37b50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
37b60 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37b70 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
37b80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37b90 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
37ba0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
37bb0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
37bc0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
37bd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37be0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37bf0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
37c00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37c10 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
37c20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
37c30 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
37c40 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
37c50 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
37c60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37c70 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
37c80 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
37c90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
37ca0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
37cb0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
37cc0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
37cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37ce0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
37cf0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
37d00 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
37d10 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
37d20 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
37d30 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
37d40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37d50 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
37d60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
37d70 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
37d80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72  ALL sqlite3_user
37d90 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
37da0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
37db0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
37dc0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
37dd0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
37de0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
37df0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
37e00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
37e10 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
37e20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37e30 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
37e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37e60 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
37e70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
37e80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
37e90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
37ea0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
37eb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
37ec0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
37ed0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
37ee0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
37ef0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
37f00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
37f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
37f20 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  te3 *SQLITE_STDC
37f30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ALL sqlite3_cont
37f40 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
37f50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
37f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37f70 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
37f80 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
37f90 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
37fa0 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
37fb0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
37fc0 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
37fd0 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
37fe0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
37ff0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
38000 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
38010 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
38020 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
38030 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
38040 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
38050 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
38060 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
38070 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
38080 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
38090 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
380a0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
380b0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
380c0 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
380d0 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
380e0 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
380f0 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
38100 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
38110 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
38120 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
38130 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
38140 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
38150 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
38160 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
38170 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38180 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
38190 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
381a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
381b0 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
381c0 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
381d0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
381e0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
381f0 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
38200 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
38210 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
38220 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
38230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38240 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
38250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38260 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
38270 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
38280 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
38290 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
382a0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
382b0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
382c0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
382d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
382e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
382f0 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  on. ^If there is
38300 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20   no metadata.** 
38310 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
38320 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  the function arg
38330 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69  ument, this sqli
38340 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
38350 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
38360 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
38370 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
38380 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
38390 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69  xdata(C,N,P,X) i
383a0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50  nterface saves P
383b0 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72   as metadata for
383c0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
383d0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
383e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
383f0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62   function.  ^Sub
38400 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
38410 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
38420 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74  auxdata(C,N) ret
38430 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d  urn P from the m
38440 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71  ost recent.** sq
38450 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
38460 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20  a(C,N,P,X) call 
38470 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
38480 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f  is still valid o
38490 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65  r.** NULL if the
384a0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
384b0 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  en discarded..**
384c0 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c   ^After each cal
384d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
384e0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
384f0 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74  ) where X is not
38500 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65   NULL,.** SQLite
38510 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
38520 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
38530 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61  tion X with para
38540 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a  meter P exactly.
38550 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68  ** once, when th
38560 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69  e metadata is di
38570 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69  scarded..** SQLi
38580 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69  te is free to di
38590 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61  scard the metada
385a0 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20  ta at any time, 
385b0 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a  including: <ul>.
385c0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65  ** <li> when the
385d0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
385e0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
385f0 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a  r changes, or.**
38600 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69   <li> when [sqli
38610 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
38620 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
38630 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66  e()] is called f
38640 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53  or the.**      S
38650 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  QL statement, or
38660 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71  .** <li> when sq
38670 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
38680 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  a() is invoked a
38690 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65  gain on the same
386a0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a   parameter, or.*
386b0 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68  * <li> during th
386c0 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74  e original sqlit
386d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
386e0 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d   call when a mem
386f0 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c  ory .**      all
38700 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
38710 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  curs. </ul>)^.**
38720 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73  .** Note the las
38730 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74  t bullet in part
38740 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73  icular.  The des
38750 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a  tructor X in .**
38760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38770 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69  data(C,N,P,X) mi
38780 6