System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1398ba8e4043550a533cdd0834bfdad1c9eab0f4:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 31 30 2e 31 2e 20 20  ersion 3.10.1.  
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 31 30 2e 31 22 0a 23 64       "3.10.1".#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 31 30  SION_NUMBER 3010
3130: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#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 36 2d 30 31 2d 31 33 20 32 31    "2016-01-13 21
3160: 3a 34 31 3a 35 36 20 32 35 34 34 31 39 63 33 36  :41:56 254419c36
3170: 37 36 36 32 32 35 63 61 35 34 32 61 65 38 37 33  766225ca542ae873
3180: 65 64 33 38 32 35 35 65 33 66 62 38 35 38 38 22  ed38255e3fb8588"
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 65  ader, and thus e
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 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure 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 49 4f 45 52 52  ine SQLITE_IOERR
7760: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
7770: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7780: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
7790: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
77a0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
77b0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
77c0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
77d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
77e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
77f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
7800: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
7810: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
7820: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
7830: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
7840: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
7850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
7860: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
7870: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
7880: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
7890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
78a0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
78b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
78c0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
78d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
78e0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
78f0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
7900: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
7910: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7920: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
7930: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
7940: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7950: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
7960: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
7970: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
7980: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
7990: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
79a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
79b0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
79c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
79d0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
79e0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
79f0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
7a00: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
7a10: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
7a20: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
7a30: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
7a40: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7a50: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
7a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7a70: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
7a80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7a90: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
7aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7ab0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
7ac0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
7ad0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
7ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7af0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
7b00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7b10: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
7b20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7b30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
7b40: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
7b50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7b60: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7b70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b80: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
7b90: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7ba0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
7bb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7bc0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
7bd0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7be0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
7bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7c00: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
7c10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7c20: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
7c30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7c40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
7c50: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
7c60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7c70: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7c80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c90: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
7ca0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7cb0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
7cc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7cd0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
7ce0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7cf0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
7d00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7d10: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
7d20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7d30: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
7d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
7d60: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
7d70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
7d80: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<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 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
7db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7dc0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7dd0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7de0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
7df0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7e00: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7e10: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
7e20: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
7e30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
7e40: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7e50: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
7e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
7e70: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
7e80: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
7e90: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
7ea0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
7eb0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
7ec0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
7ed0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
7ee0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
7ef0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
7f00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
7f10: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
7f20: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
7f30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
7f40: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7f50: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
7f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f70: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
7f80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
7f90: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7fc0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
7fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
7fe0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7ff0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8010: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
8020: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
8030: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8040: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
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 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8070: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
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 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
80b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
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 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
80f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
8100: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8120: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
8130: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
8140: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8150: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8170: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
8180: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
8190: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
81a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
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 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
81d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
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 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
8210: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
8220: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8240: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
8250: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
8290: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
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 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
82d0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
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 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
8310: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
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 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
8350: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
8360: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8380: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
8390: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
83a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
83b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
83c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83d0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
83e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
83f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8400: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8420: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
8430: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
8440: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8450: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8470: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
8480: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
8490: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
84a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
84b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
84c0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
84d0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
84e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
84f0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
8500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8510: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
8520: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
8530: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
8540: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
8550: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
8560: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
8570: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
8580: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8590: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
85a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
85b0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
85c0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
85d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
85e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
85f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
8600: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
8610: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
8620: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
8630: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8640: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
8650: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8670: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8680: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8690: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
86a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
86b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
86c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
86d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
86e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
86f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8700: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8710: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8720: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8730: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8740: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8750: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8760: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8770: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8780: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8790: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
87a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
87b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
87c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
87d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
87e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
87f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8800: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8810: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8820: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8830: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8840: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8850: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8860: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8870: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8880: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8890: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
88a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
88b0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
88c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
88d0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
88e0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
88f0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
8900: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
8910: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
8920: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
8930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
8940: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
8950: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
8960: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
8970: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
8980: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
8990: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
89a0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
89b0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
89c0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
89d0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
89e0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
89f0: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
8a00: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
8a10: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
8a20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
8a30: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
8a40: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
8a50: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
8a60: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
8a70: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
8a80: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
8a90: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
8aa0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
8ab0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
8ac0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8ad0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
8ae0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
8af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8b00: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
8b10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8b20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
8b30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8b40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8b50: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
8b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8b70: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
8b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
8b90: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
8ba0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
8bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8bc0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
8bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8be0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
8bf0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
8c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8c10: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
8c20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8c30: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
8c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8c50: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
8c60: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
8c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8c80: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
8c90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8ca0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
8cb0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8cc0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
8cd0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
8ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8cf0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
8d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
8d10: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8d20: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
8d30: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
8d40: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
8d50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
8d60: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8d70: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
8d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d90: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
8da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8db0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
8dc0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
8dd0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
8de0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
8df0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
8e00: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
8e10: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
8e20: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
8e30: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
8e40: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
8e50: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
8e60: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
8e70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8e80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8e90: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
8ea0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
8eb0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
8ec0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
8ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8ee0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
8ef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8f00: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
8f10: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
8f20: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8f30: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
8f40: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
8f50: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
8f60: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
8f70: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
8f80: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
8f90: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
8fa0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8fb0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
8fc0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
8fd0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
8fe0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
8ff0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
9000: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
9010: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
9020: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
9030: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
9040: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
9050: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
9060: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
9070: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
9080: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
9090: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
90a0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
90b0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
90c0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
90d0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
90e0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
90f0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
9100: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
9110: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
9120: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
9130: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
9140: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
9150: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
9160: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
9170: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
9180: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
9190: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
91a0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
91b0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
91c0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
91d0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
91e0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
91f0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
9200: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9210: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
9220: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
9230: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
9240: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
9250: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
9260: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
9270: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
9280: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
9290: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
92a0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
92b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
92c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
92d0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
92e0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
92f0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
9300: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
9310: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
9320: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
9330: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
9340: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
9350: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
9360: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
9370: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
9380: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
9390: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
93a0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
93b0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
93c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
93d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
93e0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
93f0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
9400: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
9410: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
9420: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
9430: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
9440: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
9450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9460: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
9470: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
9480: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
9490: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
94a0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
94b0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
94c0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
94d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
94e0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
94f0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
9500: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
9510: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
9520: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
9530: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
9540: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
9550: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
9560: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
9570: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
9580: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
9590: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
95a0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
95b0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
95c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
95d0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
95e0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
95f0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
9600: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
9610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
9620: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
9630: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
9640: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
9650: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
9660: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
9670: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
9680: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
9690: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
96a0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
96b0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
96c0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
96d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
96e0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
96f0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
9700: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
9710: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
9720: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
9730: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
9740: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
9750: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
9760: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
9770: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
9780: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
9790: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
97a0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
97b0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
97c0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
97d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
97e0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
97f0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
9800: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
9810: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
9820: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
9830: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
9840: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
9850: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
9860: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
9870: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
9880: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9890: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
98a0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
98b0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
98c0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
98d0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
98e0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
98f0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
9900: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
9910: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
9920: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
9930: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
9940: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
9950: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
9960: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
9970: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
9980: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
9990: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
99a0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
99b0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
99c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
99d0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
99e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
99f0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
9a00: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9a10: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
9a20: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
9a30: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
9a40: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
9a50: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
9a60: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
9a70: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
9a80: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
9a90: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
9aa0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
9ab0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
9ac0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
9ad0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
9ae0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
9af0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
9b00: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
9b10: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
9b20: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
9b30: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
9b40: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
9b50: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
9b60: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
9b70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
9b80: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
9b90: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
9ba0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
9bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9bc0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
9bd0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
9be0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
9bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9c00: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
9c10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9c20: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
9c30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9c40: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
9c50: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
9c60: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9c70: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
9c80: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
9c90: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
9ca0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
9cb0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
9cc0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
9cd0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
9ce0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
9cf0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
9d00: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
9d10: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
9d20: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
9d30: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
9d40: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
9d50: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
9d60: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
9d70: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
9d80: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
9d90: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
9da0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
9db0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
9dc0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
9dd0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
9de0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9df0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
9e00: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
9e10: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
9e20: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9e30: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
9e40: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
9e50: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
9e60: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
9e70: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
9e80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
9e90: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
9ea0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
9eb0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
9ec0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
9ed0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
9ee0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
9ef0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
9f00: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
9f10: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
9f20: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
9f30: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
9f40: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
9f50: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
9f60: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
9f70: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
9f80: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
9f90: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
9fa0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
9fb0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
9fc0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
9fd0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
9fe0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
9ff0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
a000: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
a010: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
a020: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
a030: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
a040: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
a050: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
a060: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
a070: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
a080: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
a090: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
a0a0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
a0b0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
a0c0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
a0d0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
a0e0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
a0f0: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
a100: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
a110: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
a120: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a130: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
a140: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
a150: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
a160: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
a170: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
a180: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a190: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
a1a0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
a1b0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
a1c0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
a1d0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
a1e0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
a1f0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
a200: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
a210: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
a220: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
a230: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
a240: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a250: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
a260: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
a270: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
a280: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
a290: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
a2a0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
a2b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a2c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a2d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
a2e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
a2f0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
a300: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
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 32  TE_IOCAP_ATOMIC2
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 34  TE_IOCAP_ATOMIC4
a350: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a360: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
a370: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a390: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
a3a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a3b0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
a3c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a3d0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
a3e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
a3f0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
a400: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
a410: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
a420: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
a430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a440: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
a450: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
a460: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
a470: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
a490: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
a4a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
a4b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
a4c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
a4d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
a4e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
a4f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
a500: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
a510: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
a520: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a530: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
a540: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
a550: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
a560: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
a570: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
a580: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
a590: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
a5a0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
a5b0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
a5c0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
a5d0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
a5e0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
a5f0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
a600: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a610: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
a620: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
a630: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
a640: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
a650: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
a660: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
a670: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
a680: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
a690: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
a6a0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
a6b0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
a6c0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
a6d0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
a6e0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
a6f0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
a700: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
a710: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
a720: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
a730: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
a740: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
a750: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
a760: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
a770: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
a780: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a790: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
a7a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
a7b0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a7c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
a7d0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
a7e0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
a7f0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a800: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
a810: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
a820: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a830: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a840: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
a850: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a860: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
a870: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
a880: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
a890: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
a8a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
a8b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
a8c0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
a8d0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
a8e0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
a8f0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
a900: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a910: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
a920: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
a930: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
a940: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
a950: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
a960: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
a980: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
a990: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a9a0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
a9b0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
a9c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a9d0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
a9e0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
a9f0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
aa00: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
aa10: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
aa20: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
aa30: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
aa40: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
aa50: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
aa60: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
aa70: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
aa80: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
aa90: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
aaa0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
aab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
aac0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
aad0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
aae0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
aaf0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
ab00: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
ab10: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
ab20: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
ab30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
ab40: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
ab50: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
ab60: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
ab70: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
ab80: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
ab90: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
aba0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
abb0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
abc0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
abd0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
abe0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
abf0: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
ac00: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
ac10: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
ac20: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
ac30: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
ac40: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
ac50: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ac60: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
ac70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ac80: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
ac90: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
aca0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
acb0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
acc0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
acd0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
ace0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
acf0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
ad00: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
ad10: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
ad20: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
ad30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
ad40: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
ad50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ad60: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
ad70: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
ad80: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
ad90: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
ada0: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
adb0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
adc0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
add0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
ade0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
adf0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
ae00: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
ae10: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
ae20: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
ae30: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
ae40: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
ae50: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
ae60: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
ae70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
ae80: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
ae90: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
aea0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
aeb0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
aec0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
aed0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
aee0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
aef0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
af00: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
af10: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
af20: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
af30: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
af40: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
af50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
af60: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
af70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
af80: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
af90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afa0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
afb0: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
afc0: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
afd0: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
afe0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
aff0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b000: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
b010: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
b020: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
b030: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
b040: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
b050: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
b060: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
b070: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
b080: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
b090: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
b0a0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
b0b0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
b0c0: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
b0d0: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
b0e0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
b0f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
b100: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
b110: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b130: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b140: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b150: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
b160: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
b170: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
b180: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
b190: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
b1a0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
b1b0: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
b1c0: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
b1d0: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
b1e0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
b1f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b200: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
b210: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
b220: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
b230: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
b240: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
b250: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
b260: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
b270: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
b280: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
b290: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
b2a0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
b2b0: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
b2c0: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
b2d0: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
b2e0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
b2f0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
b300: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
b310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b320: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b330: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b340: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b350: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
b360: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
b370: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
b380: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b390: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
b3a0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
b3b0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
b3c0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
b3d0: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
b3e0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
b3f0: 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  L_POINTER]..**.*
b400: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b410: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
b420: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b430: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
b440: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  NAL_POINTER] opc
b450: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
b460: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
b470: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
b480: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b490: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
b4a0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
b4b0: 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20   (either.** the 
b4c0: 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  [rollback journa
b4d0: 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65  l] or the [write
b4e0: 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72  -ahead log]) for
b4f0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
b500: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
b510: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
b520: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
b530: 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  LE_POINTER]..**.
b540: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b550: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
b560: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
b570: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
b580: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b590: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
b5a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
b5b0: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
b5c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
b5d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
b5e0: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
b5f0: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
b600: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
b610: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
b620: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
b630: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
b640: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
b650: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
b660: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
b670: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
b680: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
b690: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
b6a0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
b6b0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
b6c0: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
b6d0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
b6e0: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
b6f0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
b700: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
b710: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
b720: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
b730: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
b740: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
b750: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
b760: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
b770: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
b780: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
b790: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
b7a0: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
b7b0: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
b7c0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
b7d0: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
b7e0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
b7f0: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
b800: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
b810: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
b820: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
b830: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
b840: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
b850: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
b860: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
b870: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
b880: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
b890: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
b8a0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
b8b0: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
b8c0: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
b8d0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
b8e0: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
b8f0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
b900: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b910: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
b920: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
b940: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
b950: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
b960: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
b970: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
b980: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
b990: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
b9a0: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
b9b0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
b9c0: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
b9d0: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
b9e0: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
b9f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
ba00: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
ba10: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
ba20: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
ba30: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
ba40: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
ba50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
ba60: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
ba70: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
ba80: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
ba90: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
baa0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
bab0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
bac0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
bad0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
bae0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
baf0: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
bb00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bb10: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
bb20: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
bb30: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
bb40: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
bb50: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
bb60: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
bb70: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
bb80: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
bb90: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
bba0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
bbb0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
bbc0: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
bbd0: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
bbe0: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
bbf0: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
bc00: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
bc10: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
bc20: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
bc30: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
bc40: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
bc50: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
bc60: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
bc70: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
bc80: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
bc90: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
bca0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
bcb0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
bcc0: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
bcd0: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
bce0: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
bcf0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
bd00: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
bd10: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
bd20: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
bd30: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
bd40: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
bd50: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
bd60: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
bd70: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
bd80: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
bd90: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
bda0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
bdb0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bdc0: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
bdd0: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
bde0: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
bdf0: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
be00: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
be10: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
be20: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
be30: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
be40: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
be50: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
be60: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
be70: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
be80: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
be90: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
bea0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
beb0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
bec0: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
bed0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
bee0: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
bef0: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
bf00: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
bf10: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
bf20: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
bf30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
bf40: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
bf50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bf60: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
bf70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
bf80: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
bf90: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
bfa0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
bfb0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
bfc0: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
bfd0: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
bfe0: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
bff0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
c000: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
c010: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
c020: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
c030: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
c040: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
c050: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
c060: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
c070: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
c080: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
c090: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
c0a0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
c0b0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
c0c0: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
c0d0: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
c0e0: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
c0f0: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
c100: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
c110: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
c120: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
c130: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
c140: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
c150: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
c160: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
c170: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
c180: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
c190: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
c1a0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
c1b0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
c1c0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
c1d0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
c1e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c1f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
c200: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
c210: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
c220: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
c230: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
c240: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
c250: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
c260: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
c270: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
c280: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
c290: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
c2a0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
c2b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
c2c0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
c2d0: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
c2e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
c2f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
c300: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c310: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
c320: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
c330: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
c340: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
c350: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
c360: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
c370: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
c380: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
c390: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
c3a0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
c3b0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
c3c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
c3d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
c3e0: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
c3f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
c400: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
c410: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
c420: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
c430: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
c440: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
c450: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
c460: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
c470: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
c480: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
c490: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
c4a0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
c4b0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
c4c0: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
c4d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
c4e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
c4f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
c500: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
c510: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
c520: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
c530: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c540: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
c550: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c560: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
c570: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
c580: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
c590: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
c5a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
c5b0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
c5c0: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
c5d0: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
c5e0: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
c5f0: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
c600: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
c610: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
c620: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
c630: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
c640: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
c650: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
c660: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c670: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
c680: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c690: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
c6a0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
c6b0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
c6c0: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
c6d0: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
c6e0: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
c6f0: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
c700: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
c710: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
c720: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
c730: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
c740: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
c750: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
c760: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
c770: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
c780: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
c790: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
c7a0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
c7b0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
c7c0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c7d0: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
c7e0: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
c7f0: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
c800: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
c810: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
c820: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
c830: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
c840: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
c850: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
c860: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
c870: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
c880: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
c890: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
c8a0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
c8b0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
c8c0: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
c8d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
c8e0: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
c8f0: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
c900: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
c910: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
c920: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
c930: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c940: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
c950: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c960: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c970: 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64  TER] opcode find
c980: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
c990: 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20  he top-level.** 
c9a0: 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c  [VFSes] currentl
c9b0: 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65  y in use.  ^(The
c9c0: 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a   argument X in.*
c9d0: 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  * sqlite3_file_c
c9e0: 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45  ontrol(db,SQLITE
c9f0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
ca00: 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a  ER,X) must be.**
ca10: 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74   of type "[sqlit
ca20: 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68  e3_vfs] **".  Th
ca30: 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20  is opcodes will 
ca40: 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70  set *X.** to a p
ca50: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
ca60: 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a  p-level VFS.)^.*
ca70: 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72  * ^When there ar
ca80: 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73  e multiple VFS s
ca90: 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63  hims in the stac
caa0: 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66  k, this opcode f
cab0: 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65  inds the.** uppe
cac0: 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79  r-most shim only
cad0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
cae0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
caf0: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
cb00: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
cb10: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
cb20: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
cb30: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
cb40: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
cb50: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
cb60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
cb70: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
cb80: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
cb90: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
cba0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
cbb0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
cbc0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
cbd0: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
cbe0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
cbf0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
cc00: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
cc10: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
cc20: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
cc30: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
cc40: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
cc50: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
cc60: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
cc70: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
cc80: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
cc90: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
cca0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
ccb0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
ccc0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
ccd0: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
cce0: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
ccf0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
cd00: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
cd10: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
cd20: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
cd30: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
cd40: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
cd50: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
cd60: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
cd70: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
cd80: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
cd90: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
cda0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
cdb0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
cdc0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
cdd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
cde0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
cdf0: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ce00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ce10: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ce20: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ce30: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ce40: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
ce50: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
ce60: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
ce70: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
ce80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
ce90: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
cea0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
ceb0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
cec0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
ced0: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
cee0: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
cef0: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
cf00: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
cf10: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
cf20: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66  red statement if
cf30: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
cf40: 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20  s NULL, or that 
cf50: 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a  returns a copy.*
cf60: 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
cf70: 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74  string if the st
cf80: 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c  ring is non-NULL
cf90: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  ..** ^If the [SQ
cfa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cfb0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
cfc0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
cfd0: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
cfe0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
cff0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
d000: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
d010: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
d020: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
d030: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
d040: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
d050: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
d060: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
d070: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
d080: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
d090: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d0a0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
d0b0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
d0c0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
d0d0: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
d0e0: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
d0f0: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
d100: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
d110: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
d120: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
d130: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d140: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
d150: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
d160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
d170: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d  ANDLER].** file-
d180: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
d190: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
d1a0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
d1b0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
d1c0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
d1d0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
d1e0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
d1f0: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
d200: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
d210: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
d220: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
d230: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
d240: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
d250: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
d260: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
d270: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
d280: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
d290: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
d2a0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
d2b0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
d2c0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
d2d0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
d2e0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
d2f0: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
d300: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
d310: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
d320: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
d330: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
d340: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
d350: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
d360: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
d370: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
d380: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
d390: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
d3a0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
d3b0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
d3c0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
d3d0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
d3e0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
d3f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d400: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d410: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
d420: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
d430: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d440: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66  _TEMPFILENAME] f
d450: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74  ile-control.** t
d460: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65  o have SQLite ge
d470: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70  nerate a.** temp
d480: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75  orary filename u
d490: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
d4a0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20  gorithm that is 
d4b0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65  followed to gene
d4c0: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  rate.** temporar
d4d0: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20  y filenames for 
d4e0: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20  TEMP tables and 
d4f0: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75  other internal u
d500: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67  ses.  The.** arg
d510: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
d520: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77  a char** which w
d530: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69  ill be filled wi
d540: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a  th the filename.
d550: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ** written into 
d560: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
d570: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
d580: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61  lloc()].  The ca
d590: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69  ller should.** i
d5a0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
d5b0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65  ree()] on the re
d5c0: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20  sult to avoid a 
d5d0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a  memory leak..**.
d5e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d5f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
d600: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
d610: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
d630: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
d640: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
d650: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
d660: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
d670: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
d680: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
d690: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
d6a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d6b0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
d6c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
d6d0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
d6e0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
d6f0: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
d700: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
d710: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
d720: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
d730: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
d740: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
d750: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
d760: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61  ged if.** the va
d770: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70  lue originally p
d780: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67  ointed to is neg
d790: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68  ative, and so th
d7a0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20  e current limit 
d7b0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69  .** can be queri
d7c0: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e  ed by passing in
d7d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
d7e0: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e  negative number.
d7f0: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63    This.** file-c
d800: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69  ontrol is used i
d810: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70  nternally to imp
d820: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d  lement [PRAGMA m
d830: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a  map_size]..**.**
d840: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d850: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54  NTL_TRACE]].** T
d860: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d870: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e  _TRACE] file con
d880: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64  trol provides ad
d890: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69  visory informati
d8a0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53  on.** to the VFS
d8b0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20   about what the 
d8c0: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66  higher layers of
d8d0: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63   the SQLite stac
d8e0: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20  k are doing..** 
d8f0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  This file contro
d900: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d  l is used by som
d910: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74  e VFS activity t
d920: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a  racing [shims]..
d930: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
d940: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  is a zero-termin
d950: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69  ated string.  Hi
d960: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74  gher layers in t
d970: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61  he.** SQLite sta
d980: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20  ck may generate 
d990: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69  instances of thi
d9a0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d9b0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  f.** the [SQLITE
d9c0: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  _USE_FCNTL_TRACE
d9d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
d9e0: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
d9f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
da00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
da10: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  OVED]].** The [S
da20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
da30: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74  MOVED] file cont
da40: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
da50: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
da60: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
da70: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74  n integer and it
da80: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61   writes a boolea
da90: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  n into that inte
daa0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a  ger depending.**
dab0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e   on whether or n
dac0: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20  ot the file has 
dad0: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f  been renamed, mo
dae0: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ved, or deleted 
daf0: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20  since it.** was 
db00: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a  first opened..**
db10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
db20: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
db30: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65  _HANDLE]].** The
db40: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
db50: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
db60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
db70: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
db80: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
db90: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
dba0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
dbb0: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68   swap the file h
dbc0: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f  andle with the o
dbd0: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ne.** pointed to
dbe0: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67   by the pArg arg
dbf0: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70  ument.  This cap
dc00: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20  ability is used 
dc10: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a  during testing.*
dc20: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  * and only needs
dc30: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
dc40: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
dc50: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  T is defined..**
dc60: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
dc70: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
dc80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
dc90: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
dca0: 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  K] is a signal t
dcb0: 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20  o the VFS layer 
dcc0: 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a  that it might.**
dcd0: 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73   be advantageous
dce0: 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65   to block on the
dcf0: 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69   next WAL lock i
dd00: 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f  f the lock is no
dd10: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  t immediately.**
dd20: 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65   available.  The
dd30: 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69   WAL subsystem i
dd40: 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61  ssues this signa
dd50: 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a  l during rare.**
dd60: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69   circumstances i
dd70: 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61  n order to fix a
dd80: 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72   problem with pr
dd90: 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e  iority inversion
dda0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
ddb0: 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74  s should <em>not
ddc0: 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66  </em> use this f
ddd0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a  ile-control..**.
dde0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ddf0: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a  FCNTL_ZIPVFS]].*
de00: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
de10: 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f  NTL_ZIPVFS] opco
de20: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
de30: 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79  d by zipvfs only
de40: 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56  . All other.** V
de50: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
de60: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
de70: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
de80: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
de90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d  LITE_FCNTL_RBU]]
dea0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
deb0: 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64  FCNTL_RBU] opcod
dec0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
ded0: 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20   by the special 
dee0: 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74  VFS used by.** t
def0: 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e  he RBU extension
df00: 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65   only.  All othe
df10: 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  r VFS should ret
df20: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
df30: 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20  UND for.** this 
df40: 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75  opcode.  .** </u
df50: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
df60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
df70: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
df80: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
df90: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
dfa0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
dfb0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
dfc0: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
dfd0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
dfe0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
dff0: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
e000: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
e010: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
e020: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
e030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
e040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e050: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
e060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
e070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e080: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
e090: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
e0a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e0b0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
e0c0: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
e0d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e0e0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
e0f0: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
e100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e110: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
e120: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
e130: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e140: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
e150: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
e160: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e170: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
e180: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
e190: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
e1a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
e1b0: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
e1c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
e1d0: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
e1e0: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
e1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
e200: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
e210: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
e220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
e230: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
e240: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
e250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
e260: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
e270: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
e280: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
e290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e2a0: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
e2b0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
e2c0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
e2d0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
e2e0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
e2f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e300: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
e310: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
e320: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
e330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e340: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
e350: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
e360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e370: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
e380: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
e390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e3a0: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
e3b0: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
e3c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e3d0: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
e3e0: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
e3f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e400: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
e410: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
e420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e430: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
e440: 20 20 20 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64          28../* d
e450: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
e460: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e470: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
e480: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
e490: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
e4a0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
e4b0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
e4c0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
e4d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
e4e0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
e4f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
e500: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
e510: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
e520: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
e530: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
e540: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
e550: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
e560: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
e570: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
e580: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
e590: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
e5a0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
e5b0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
e5c0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
e5d0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
e5e0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
e5f0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
e600: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
e610: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
e620: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
e630: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
e640: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
e650: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
e660: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
e670: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
e680: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
e690: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
e6a0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
e6b0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e6c0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
e6d0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
e6e0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e6f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
e700: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
e710: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
e720: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
e730: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
e740: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
e750: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
e760: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
e770: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
e780: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
e790: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e7a0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
e7b0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
e7c0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
e7d0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
e7e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
e7f0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
e800: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
e810: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
e820: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
e830: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e840: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
e850: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
e860: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
e870: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
e880: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
e890: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
e8a0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
e8b0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
e8c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e8d0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
e8e0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
e8f0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
e900: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
e910: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
e920: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
e930: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
e940: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
e950: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e960: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e970: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e980: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e990: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e9a0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e9b0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e9c0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e9d0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e9e0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e9f0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
ea00: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
ea10: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
ea20: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
ea30: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
ea40: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
ea50: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
ea60: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
ea70: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
ea80: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
ea90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
eaa0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
eab0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
eac0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
ead0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
eae0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
eaf0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
eb00: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
eb10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
eb20: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
eb30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
eb40: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
eb50: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
eb60: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
eb70: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
eb80: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
eb90: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
eba0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
ebb0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
ebc0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
ebd0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
ebe0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
ebf0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
ec00: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
ec10: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
ec20: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
ec30: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
ec40: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
ec50: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
ec60: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
ec70: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
ec80: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
ec90: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
eca0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
ecb0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
ecc0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
ecd0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
ece0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
ecf0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
ed00: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
ed10: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
ed20: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
ed30: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
ed40: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
ed50: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
ed60: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
ed70: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
ed80: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
ed90: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
eda0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
edb0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
edc0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
edd0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
ede0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
edf0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
ee00: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
ee10: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
ee20: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
ee30: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
ee40: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
ee50: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
ee60: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
ee70: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
ee80: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
ee90: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
eea0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
eeb0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
eec0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
eed0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
eee0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
eef0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ef00: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ef10: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ef20: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ef30: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
ef40: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
ef50: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
ef60: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
ef70: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
ef80: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
ef90: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
efa0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
efb0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
efc0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
efd0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
efe0: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eff0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
f000: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
f010: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
f020: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
f030: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
f040: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
f050: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
f060: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
f070: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
f080: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
f090: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
f0a0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
f0b0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
f0c0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
f0d0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
f0e0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f0f0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
f100: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
f110: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
f120: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
f130: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
f140: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
f150: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
f160: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
f170: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
f180: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
f190: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
f1a0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
f1b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
f1c0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
f1d0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
f1e0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
f1f0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
f200: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
f210: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
f220: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
f230: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
f240: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
f250: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
f260: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
f270: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
f280: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
f290: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f2a0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
f2b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
f2c0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
f2d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
f2e0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
f2f0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
f300: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
f310: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
f320: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
f330: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
f340: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
f350: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
f360: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
f370: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
f380: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
f390: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
f3a0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
f3b0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
f3c0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
f3d0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
f3e0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
f3f0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
f400: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
f410: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
f420: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
f430: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
f440: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
f450: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
f460: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
f470: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
f480: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
f490: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f4a0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f4b0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f4c0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f4d0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f4e0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f4f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f500: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f510: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f520: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f530: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f540: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f550: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f560: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f570: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f580: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f590: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f5a0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f5b0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f5c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f5d0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f5e0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f5f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f600: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f610: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f620: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f630: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f640: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f650: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f660: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f670: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f680: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f690: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f6a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f6b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f6c0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f6d0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f6e0: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f6f0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f700: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f710: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f720: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f730: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f740: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f750: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f760: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f770: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f780: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f790: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f7a0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f7b0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f7c0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f7d0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f7e0: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f7f0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f800: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f810: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f820: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f830: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f840: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f850: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f860: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f870: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f880: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f890: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f8a0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f8b0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f8c0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f8d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f8e0: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f8f0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f900: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f910: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f920: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f930: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f940: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f950: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f960: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f970: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f980: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f990: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f9a0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f9b0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f9c0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f9d0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f9e0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f9f0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
fa00: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
fa10: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
fa20: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
fa30: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
fa40: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
fa50: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
fa60: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
fa70: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
fa80: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
fa90: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
faa0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
fab0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
fac0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
fad0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
fae0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
faf0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
fb00: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
fb10: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
fb20: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
fb30: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
fb40: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
fb50: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
fb60: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
fb70: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
fb80: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
fb90: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
fba0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
fbb0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
fbc0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
fbd0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
fbe0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
fbf0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
fc00: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
fc10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
fc20: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
fc30: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
fc40: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
fc50: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
fc60: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
fc70: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
fc80: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
fc90: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
fca0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
fcb0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
fcc0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
fcd0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
fce0: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
fcf0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
fd00: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
fd10: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
fd20: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
fd30: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
fd40: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
fd50: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
fd60: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
fd70: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
fd80: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
fd90: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
fda0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
fdb0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
fdc0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
fdd0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
fde0: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
fdf0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
fe00: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
fe10: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
fe20: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
fe30: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
fe40: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
fe50: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
fe60: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
fe70: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
fe80: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
fe90: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
fea0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
feb0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
fec0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
fed0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
fee0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
fef0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
ff00: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
ff10: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
ff20: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
ff30: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
ff40: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
ff50: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
ff60: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
ff70: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
ff80: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
ff90: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
ffa0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
ffb0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
ffc0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
ffd0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
ffe0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
fff0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
10000 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
10010 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
10020 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
10030 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
10040 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
10050 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
10060 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
10070 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
10080 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
10090 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
100a0 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
100b0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
100c0 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
100d0 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
100e0 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
100f0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
10100 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
10110 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
10120 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
10130 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
10140 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
10150 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
10160 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
10170 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
10180 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
10190 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
101a0 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
101b0 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
101c0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
101d0 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
101e0 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
101f0 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
10200 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
10210 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
10220 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
10230 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
10240 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
10250 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
10260 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
10270 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
10280 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
10290 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
102a0 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
102b0 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
102c0 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
102d0 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
102e0 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
102f0 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
10300 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
10310 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
10320 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
10330 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
10340 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
10350 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
10360 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
10370 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
10380 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
10390 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
103a0 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
103b0 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
103c0 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
103d0 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
103e0 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
103f0 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
10400 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
10410 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
10420 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
10430 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
10440 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
10450 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
10460 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
10470 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
10480 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
10490 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
104a0 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
104b0 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
104c0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
104d0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
104e0 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
104f0 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
10500 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
10510 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
10520 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
10530 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
10540 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
10550 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
10560 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
10570 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
10580 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
10590 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
105a0 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
105b0 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
105c0 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
105d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
105e0 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
105f0 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
10600 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
10610 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
10620 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
10630 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
10640 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
10650 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
10660 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
10670 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
10680 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
10690 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
106a0 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
106b0 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
106c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
106d0 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
106e0 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
106f0 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
10700 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10710 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
10720 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
10730 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
10740 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
10750 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
10760 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10770 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
10780 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
10790 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
107a0 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
107b0 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
107c0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
107d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
107e0 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
107f0 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
10800 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10810 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10820 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
10830 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
10840 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
10850 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10860 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10870 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
10880 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
10890 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
108a0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
108b0 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
108c0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
108d0 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
108e0 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
108f0 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
10900 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
10910 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
10920 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
10930 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
10940 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
10950 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
10960 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
10970 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
10980 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
10990 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
109a0 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
109b0 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
109c0 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
109d0 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
109e0 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
109f0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
10a00 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
10a10 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
10a20 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
10a30 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
10a40 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
10a50 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
10a60 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
10a70 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
10a80 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
10a90 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
10aa0 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
10ab0 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
10ac0 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
10ad0 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10ae0 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
10af0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
10b00 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
10b10 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
10b20 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
10b30 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
10b40 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
10b50 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
10b60 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
10b70 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
10b80 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
10b90 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
10ba0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10bb0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
10bc0 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
10bd0 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
10be0 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
10bf0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10c00 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10c10 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10c20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
10c30 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
10c40 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10c50 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
10c60 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
10c70 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
10c80 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
10c90 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
10ca0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
10cb0 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
10cc0 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
10cd0 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
10ce0 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
10cf0 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
10d00 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
10d10 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
10d20 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
10d30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10d40 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
10d50 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
10d60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
10d70 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
10d80 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
10d90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10da0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
10db0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
10dc0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
10dd0 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
10de0 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
10df0 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
10e00 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
10e10 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
10e20 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
10e30 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10e40 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
10e50 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
10e60 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
10e70 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
10e80 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10e90 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10ea0 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
10eb0 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
10ec0 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
10ed0 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
10ee0 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
10ef0 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
10f00 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
10f10 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
10f20 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
10f30 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
10f40 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
10f50 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
10f60 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10f70 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
10f80 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
10f90 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
10fa0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
10fb0 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
10fc0 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
10fd0 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
10fe0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
10ff0 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
11000 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
11010 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
11020 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
11030 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
11040 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
11050 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
11060 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
11070 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
11080 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
11090 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
110a0 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
110b0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
110c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
110d0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
110e0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
110f0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
11100 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
11110 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
11120 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
11130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11140 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
11150 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
11160 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
11170 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
11180 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
11190 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
111a0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
111b0 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
111c0 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
111d0 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
111e0 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
111f0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
11200 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
11210 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
11220 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
11230 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
11240 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
11250 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
11260 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
11270 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
11280 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
11290 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
112a0 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
112b0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
112c0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
112d0 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
112e0 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
112f0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
11300 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
11310 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
11320 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
11330 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
11340 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
11350 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
11360 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
11370 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
11380 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
11390 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
113a0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
113b0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
113c0 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
113d0 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
113e0 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
113f0 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
11400 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
11410 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
11420 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
11430 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
11440 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
11450 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
11460 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
11470 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
11480 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
11490 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
114a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
114b0 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
114c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
114d0 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
114e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
114f0 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
11500 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
11510 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
11520 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
11530 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
11540 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
11550 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
11560 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
11570 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
11580 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
11590 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
115a0 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
115b0 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
115c0 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
115d0 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
115e0 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
115f0 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
11600 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
11610 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
11620 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
11630 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
11640 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11650 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11660 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
11670 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
11680 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
11690 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
116a0 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
116b0 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
116c0 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
116d0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
116e0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
116f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11700 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
11710 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
11720 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
11730 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
11740 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
11750 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
11760 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
11770 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
11780 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
11790 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
117a0 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
117b0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
117c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
117d0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
117e0 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
117f0 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
11800 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
11810 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11820 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
11830 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
11840 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
11850 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
11860 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
11870 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11880 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
11890 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
118a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
118b0 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
118c0 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
118d0 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
118e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
118f0 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
11900 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
11910 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
11920 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
11930 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
11940 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11950 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
11960 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
11970 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
11980 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
11990 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
119a0 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
119b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
119c0 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
119d0 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
119e0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
119f0 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
11a00 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
11a10 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
11a20 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
11a30 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
11a40 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
11a50 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
11a60 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11a70 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
11a80 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
11a90 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
11aa0 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
11ab0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
11ac0 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
11ad0 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
11ae0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
11af0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
11b00 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
11b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11b20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
11b30 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
11b40 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
11b50 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
11b60 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
11b70 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
11b80 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
11b90 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
11ba0 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
11bb0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
11bc0 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
11bd0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
11be0 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
11bf0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
11c00 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
11c10 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
11c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
11c30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11c40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
11c50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
11c60 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
11c70 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
11c80 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11c90 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
11ca0 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
11cb0 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
11cc0 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
11cd0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
11ce0 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
11cf0 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
11d00 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
11d10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
11d20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
11d30 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
11d40 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11d50 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
11d60 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
11d70 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
11d80 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
11d90 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
11da0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
11db0 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
11dc0 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
11dd0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11de0 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
11df0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
11e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
11e10 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
11e20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
11e30 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11e40 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
11e50 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
11e60 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
11e70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
11e80 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
11e90 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
11ea0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
11eb0 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
11ec0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11ed0 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
11ee0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
11ef0 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
11f00 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
11f10 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
11f20 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
11f30 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
11f40 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
11f50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
11f60 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
11f70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
11f80 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
11f90 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11fa0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11fb0 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
11fc0 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
11fd0 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
11fe0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
11ff0 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
12000 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
12010 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
12020 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
12030 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
12040 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
12050 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
12060 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
12070 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
12080 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12090 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
120a0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
120b0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
120c0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
120d0 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
120e0 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
120f0 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
12100 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
12110 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
12120 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
12130 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12140 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
12150 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
12160 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
12170 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
12180 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
12190 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
121a0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
121b0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
121c0 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
121d0 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
121e0 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
121f0 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
12200 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
12210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
12220 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
12230 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
12240 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
12250 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
12260 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
12270 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
12280 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
12290 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
122a0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
122b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
122c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
122d0 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
122e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
122f0 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
12300 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
12310 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
12320 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
12330 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
12340 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
12350 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
12360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
12370 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
12380 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
12390 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
123a0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
123b0 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
123c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
123d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
123e0 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
123f0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
12400 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
12410 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
12420 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
12430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
12440 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
12450 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
12460 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
12470 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12480 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
12490 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
124a0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
124b0 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
124c0 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
124d0 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
124e0 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
124f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
12500 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
12510 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
12520 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12530 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
12540 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
12550 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
12560 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
12570 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
12580 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
12590 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
125a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
125b0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
125c0 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
125d0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
125e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
125f0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
12600 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
12610 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
12620 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53  ** failure..*/.S
12630 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12640 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
12650 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12660 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
12670 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
12680 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75  CALL sqlite3_shu
12690 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  tdown(void);.SQL
126a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
126b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
126c0 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
126d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
126e0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
126f0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
12700 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
12710 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
12720 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
12730 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
12740 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12750 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
12760 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
12770 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
12780 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
12790 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
127a0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
127b0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
127c0 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
127d0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
127e0 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
127f0 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
12800 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
12810 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
12820 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
12830 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
12840 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
12850 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
12860 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
12870 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
12880 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
12890 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
128a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
128b0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
128c0 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
128d0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
128e0 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
128f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
12900 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
12910 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
12920 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
12930 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12940 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
12950 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
12960 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
12970 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
12980 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
12990 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
129a0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
129b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
129c0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
129d0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
129e0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
129f0 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
12a00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
12a10 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
12a20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12a30 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
12a40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
12a50 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
12a60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
12a70 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
12a80 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
12a90 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
12aa0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
12ab0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
12ac0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
12ad0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
12ae0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
12af0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12b00 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
12b10 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
12b20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12b30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
12b40 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
12b50 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
12b60 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
12b70 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
12b80 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
12b90 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
12ba0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
12bb0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
12bc0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
12bd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
12be0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12bf0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
12c00 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
12c10 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
12c20 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
12c30 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
12c40 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
12c50 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
12c60 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
12c70 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
12c80 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
12c90 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
12ca0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
12cb0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
12cc0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
12cd0 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  int SQLITE_CDECL
12ce0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12cf0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
12d00 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
12d10 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
12d20 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
12d30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
12d40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12d50 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
12d60 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
12d70 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
12d80 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
12d90 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
12da0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
12db0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
12dc0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
12dd0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
12de0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
12df0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
12e00 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
12e10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12e20 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
12e30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12e40 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
12e50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12e60 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
12e70 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
12e80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
12e90 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12ea0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
12eb0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
12ec0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
12ed0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
12ee0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
12ef0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12f00 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
12f10 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
12f20 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12f30 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
12f40 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
12f50 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
12f60 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
12f70 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12f80 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
12f90 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
12fa0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
12fb0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
12fc0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
12fd0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12fe0 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62  CDECL sqlite3_db
12ff0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
13000 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
13010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13020 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
13030 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
13040 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
13050 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
13060 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
13070 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
13080 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
13090 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
130a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
130b0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
130c0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
130d0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
130e0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
130f0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
13100 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13110 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
13120 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
13130 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13140 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
13150 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13160 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
13170 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13180 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
13190 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
131a0 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
131b0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
131c0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
131d0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
131e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
131f0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
13200 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
13210 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
13220 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
13230 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
13240 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
13250 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13260 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
13270 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
13280 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
13290 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
132a0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
132b0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
132c0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
132d0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
132e0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
132f0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
13300 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
13310 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
13320 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
13330 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
13340 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
13350 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
13360 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
13370 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
13380 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
13390 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
133a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
133b0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
133c0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
133d0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
133e0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
133f0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
13400 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
13410 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
13420 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
13430 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
13440 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
13450 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
13460 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
13470 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
13480 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
13490 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
134a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
134b0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
134c0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
134d0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
134e0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
134f0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
13500 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
13510 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
13520 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
13530 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
13540 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
13550 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13560 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
13570 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
13580 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
13590 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
135a0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
135b0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
135c0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
135d0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
135e0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
135f0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
13600 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
13610 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
13620 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
13630 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
13640 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
13650 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
13660 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
13670 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
13680 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
13690 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
136a0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
136b0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
136c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
136d0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
136e0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
136f0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
13700 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
13710 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
13720 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
13730 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
13740 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
13750 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
13760 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
13770 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
13780 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
13790 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
137a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
137b0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
137c0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
137d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
137e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
137f0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
13800 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
13810 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
13820 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
13830 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
13840 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
13850 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
13860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
13870 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
13880 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
13890 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
138a0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
138b0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
138c0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
138d0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
138e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
138f0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
13900 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
13910 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
13920 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
13930 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
13940 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
13950 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
13960 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
13970 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
13980 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
13990 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
139a0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
139b0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
139c0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
139d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
139e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
139f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
13a00 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
13a10 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
13a20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
13a30 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
13a40 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
13a50 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
13a60 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
13a70 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
13a80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13a90 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
13aa0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
13ab0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
13ac0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
13ad0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
13ae0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
13af0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
13b00 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
13b10 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
13b20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
13b30 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13b40 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
13b50 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
13b60 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
13b70 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
13b80 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
13b90 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
13ba0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
13bb0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
13bc0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
13bd0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
13be0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
13bf0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
13c00 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
13c10 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
13c20 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
13c30 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
13c40 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
13c50 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
13c60 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
13c70 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
13c80 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
13c90 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
13ca0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
13cb0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
13cc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
13cd0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
13ce0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
13cf0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
13d00 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
13d10 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
13d20 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
13d30 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
13d40 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
13d50 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
13d60 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
13d70 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
13d80 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
13d90 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
13da0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
13db0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
13dc0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
13dd0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
13de0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
13df0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
13e00 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
13e10 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
13e20 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
13e30 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
13e40 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
13e50 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
13e60 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
13e70 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
13e80 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
13e90 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13ea0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13eb0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
13ec0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
13ed0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
13ee0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
13ef0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
13f00 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
13f10 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
13f20 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
13f30 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
13f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13f50 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
13f60 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
13f70 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
13f80 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
13f90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
13fa0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
13fb0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
13fc0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
13fd0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
13fe0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
13ff0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
14000 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
14010 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
14020 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
14030 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14040 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
14050 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
14060 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
14070 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
14080 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
14090 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
140a0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
140b0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
140c0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
140d0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
140e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
140f0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
14100 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
14110 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
14120 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
14130 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
14140 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
14150 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
14160 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
14170 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
14180 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14190 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
141a0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
141b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
141c0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
141d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
141e0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
141f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
14200 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
14210 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
14220 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
14230 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
14240 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
14250 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
14260 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
14270 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
14280 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
14290 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
142a0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
142b0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
142c0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
142d0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
142e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
142f0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14300 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14310 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14320 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14330 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
14340 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
14350 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
14360 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
14370 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
14380 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
14390 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
143a0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
143b0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
143c0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
143d0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
143e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
143f0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
14400 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
14410 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14420 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14430 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
14440 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
14450 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
14460 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
14470 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
14480 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
14490 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
144a0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
144b0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
144c0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
144d0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
144e0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
144f0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
14500 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14510 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
14520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
14530 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
14540 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
14550 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
14560 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
14570 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
14580 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
14590 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
145a0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
145b0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
145c0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
145d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
145e0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
145f0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14600 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
14610 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
14620 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
14630 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
14640 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
14650 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
14660 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
14670 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14680 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14690 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
146a0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
146b0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
146c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
146d0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
146e0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
146f0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
14700 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
14710 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14720 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14730 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14740 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14750 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14760 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14770 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
14780 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
14790 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
147a0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
147b0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
147c0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
147d0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
147e0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
147f0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
14800 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
14810 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
14820 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14830 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
14840 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
14850 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
14860 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
14870 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
14880 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
14890 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
148a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
148b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
148c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
148d0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
148e0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
148f0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
14900 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14910 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
14920 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
14930 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
14940 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
14950 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
14960 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
14970 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
14980 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14990 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
149a0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
149b0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
149c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
149d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
149e0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
149f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14a00 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
14a10 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
14a20 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
14a30 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14a40 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14a50 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14a60 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14a70 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14a80 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14a90 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14aa0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
14ab0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
14ac0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14ad0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
14ae0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
14af0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
14b00 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
14b10 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
14b20 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14b30 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
14b40 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
14b50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14b60 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
14b70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14b80 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
14b90 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14ba0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
14bb0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14bc0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14bd0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
14be0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14bf0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14c00 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14c10 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
14c20 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
14c30 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
14c40 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
14c50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14c60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14c70 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
14c80 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
14c90 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
14ca0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
14cb0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
14cc0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
14cd0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
14ce0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
14cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
14d00 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14d10 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
14d20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
14d30 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
14d40 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
14d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14d60 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
14d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14d80 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
14d90 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14da0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
14db0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14dc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14dd0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
14de0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
14df0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
14e00 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14e10 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14e20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
14e30 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
14e40 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
14e50 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14e60 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
14e70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
14e80 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14e90 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14ea0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14eb0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
14ec0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
14ed0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
14ee0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
14ef0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
14f00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
14f10 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
14f20 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
14f30 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
14f40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14f50 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14f60 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
14f70 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14f80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14f90 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14fa0 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
14fb0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14fc0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
14fd0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
14fe0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14ff0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
15000 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
15010 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
15020 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15030 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
15040 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
15050 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
15060 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
15070 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
15080 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
15090 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
150a0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
150b0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
150c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
150d0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
150e0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
150f0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
15100 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
15110 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
15120 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
15130 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
15140 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
15150 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
15160 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
15170 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
15180 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
15190 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
151a0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
151b0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
151c0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
151d0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
151e0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
151f0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
15200 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
15210 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
15220 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15230 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
15240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
15250 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
15260 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15270 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
15280 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
15290 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
152a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
152b0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
152c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
152d0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
152e0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
152f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15300 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
15310 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
15320 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
15330 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
15340 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
15350 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
15360 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
15370 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
15380 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
15390 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
153a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
153b0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
153c0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
153d0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
153e0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
153f0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
15400 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
15410 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
15420 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
15430 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
15440 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
15450 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
15460 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
15470 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
15480 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
15490 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
154a0 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
154b0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
154c0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
154d0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
154e0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
154f0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
15500 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
15510 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
15520 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
15530 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15540 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
15550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
15560 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
15570 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
15580 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
15590 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
155a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
155b0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
155c0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
155d0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
155e0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
155f0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
15600 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
15610 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
15620 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
15630 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
15640 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
15650 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
15660 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15670 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
15680 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
15690 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
156a0 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
156b0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
156c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
156d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
156e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
156f0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
15700 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
15710 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15720 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
15730 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f  specifies a memo
15740 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20  ry pool.** that 
15750 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
15760 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
15770 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
15780 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
15790 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
157a0 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
157b0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
157c0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f  n option is a no
157d0 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63  -op if an applic
157e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
157f0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
15800 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
15810 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ded using the [S
15820 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15830 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65  CHE2]..** ^There
15840 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
15850 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15860 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
15870 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
15880 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
15890 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74  memory (pMem), t
158a0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
158b0 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
158c0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
158d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65   number of cache
158e0 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   lines (N)..** T
158f0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
15900 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
15910 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
15920 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
15930 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
15940 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
15950 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
15960 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
15970 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
15980 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
15990 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
159a0 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
159b0 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
159c0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
159d0 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45  ed using [SQLITE
159e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
159f0 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73  DRSZ]..** ^It is
15a00 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
15a10 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
15a20 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20   memory,.** for 
15a30 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  the sz parameter
15a40 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68   to be larger th
15a50 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54  an necessary.  T
15a60 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d  he pMem.** argum
15a70 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68  ent must be eith
15a80 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
15a90 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  r or a pointer t
15aa0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  o an 8-byte.** a
15ab0 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
15ac0 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
15ad0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f  st sz*N bytes, o
15ae0 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73  therwise.** subs
15af0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
15b00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
15b10 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e   ^When pMem is n
15b20 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
15b30 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75  will strive to u
15b40 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
15b50 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74  ovided.** to sat
15b60 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20  isfy page cache 
15b70 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62  needs, falling b
15b80 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ack to [sqlite3_
15b90 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20  malloc()] if.** 
15ba0 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  a page cache lin
15bb0 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e  e is larger than
15bc0 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20   sz bytes or if 
15bd0 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20  all of the pMem 
15be0 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68  buffer.** is exh
15bf0 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70  austed..** ^If p
15c00 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  Mem is NULL and 
15c10 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  N is non-zero, t
15c20 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73  hen each databas
15c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15c40 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20  does an initial 
15c50 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  bulk allocation 
15c60 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
15c70 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73  emory.** from [s
15c80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15c90 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20   sufficient for 
15ca0 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66  N cache lines if
15cb0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f   N is positive o
15cc0 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20  r.** of -1024*N 
15cd0 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65  bytes if N is ne
15ce0 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64  gative, . ^If ad
15cf0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
15d00 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
15d10 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
15d20 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
15d30 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a  by the initial.*
15d40 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  * allocation, th
15d50 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  en SQLite goes t
15d60 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
15d70 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20  c()] separately 
15d80 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69  for each.** addi
15d90 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e  tional cache lin
15da0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15db0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
15dc0 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
15dd0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
15de0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15e00 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
15e10 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
15e20 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
15e30 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
15e40 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
15e50 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
15e60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15e70 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
15e80 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
15e90 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
15ea0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a  _SCRATCH] and.**
15eb0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15ec0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
15ed0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15ee0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
15ef0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15f00 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
15f10 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
15f20 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
15f30 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
15f40 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
15f50 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
15f60 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
15f70 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
15f80 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
15f90 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15fa0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
15fc0 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
15fd0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
15fe0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
15ff0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
16000 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
16010 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
16020 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
16030 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
16040 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
16050 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
16060 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
16070 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
16080 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
16090 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
160a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
160b0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
160c0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
160d0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
160e0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
160f0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
16100 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
16110 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
16120 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
16130 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
16140 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
16150 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
16160 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
16170 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
16180 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
16190 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
161a0 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
161b0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
161c0 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
161d0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
161e0 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
161f0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
16200 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
16210 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
16220 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
16230 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
16240 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
16250 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
16260 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
16270 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
16280 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
16290 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
162a0 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
162b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
162c0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
162d0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
162e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
162f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16300 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
16310 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16320 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
16330 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
16340 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
16350 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
16360 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
16370 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
16380 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
16390 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
163a0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
163b0 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
163c0 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
163d0 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
163e0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
163f0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
16400 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
16410 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
16420 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
16430 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
16440 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
16450 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
16460 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
16470 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
16480 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
16490 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
164a0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
164b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
164c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
164d0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
164e0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
164f0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
16500 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
16510 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
16520 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
16530 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
16540 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
16550 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
16560 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16570 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
16580 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
16590 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
165a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
165b0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
165c0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
165d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
165e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
165f0 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
16600 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16610 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16620 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16630 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
16640 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
16650 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
16660 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
16670 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
16680 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
16690 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
166a0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
166b0 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
166c0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
166d0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
166e0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
166f0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
16700 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
16710 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
16720 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
16730 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
16740 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
16750 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
16760 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
16770 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
16780 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
16790 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
167a0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
167b0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
167c0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
167d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
167e0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
167f0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
16800 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
16810 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
16820 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
16830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
16840 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
16850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16860 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
16870 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
16880 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
16890 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
168a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
168b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
168c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
168d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
168e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
168f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16900 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
16910 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
16920 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
16930 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
16940 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
16950 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
16960 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
16970 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
16980 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16990 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
169a0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
169b0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
169c0 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
169d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
169e0 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
169f0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
16a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
16a10 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
16a20 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
16a30 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
16a40 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
16a50 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
16a60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16a70 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
16a80 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
16a90 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
16aa0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
16ab0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
16ac0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
16ad0 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
16ae0 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
16af0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16b00 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
16b10 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16b20 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
16b30 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
16b40 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16b50 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
16b60 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16b70 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
16b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
16b90 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16ba0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
16bb0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
16bc0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
16bd0 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
16be0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
16bf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
16c00 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
16c10 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
16c20 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16c30 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16c40 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
16c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16c60 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
16c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16c80 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
16c90 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
16ca0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16cb0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
16cc0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16cd0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
16ce0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
16cf0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16d00 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
16d10 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
16d20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
16d30 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
16d40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
16d50 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
16d60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
16d80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16d90 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
16da0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
16db0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
16dc0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
16dd0 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
16de0 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
16df0 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
16e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16e10 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
16e20 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
16e30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
16e40 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
16e50 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
16e60 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
16e70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
16e80 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
16e90 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
16ea0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
16eb0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
16ec0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
16ed0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
16ee0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
16ef0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
16f00 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
16f10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
16f20 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
16f30 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
16f40 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
16f50 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
16f60 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
16f70 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
16f80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16f90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16fa0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
16fb0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
16fc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
16fd0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
16fe0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16ff0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
17000 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
17010 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
17020 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
17030 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
17040 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
17050 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
17060 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17070 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
17080 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
17090 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
170a0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
170b0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
170c0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
170d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
170e0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
170f0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
17100 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
17110 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
17120 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
17130 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
17140 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
17150 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
17160 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
17170 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
17180 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
17190 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
171a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
171b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
171c0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
171d0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
171e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
171f0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
17200 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
17210 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
17220 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
17230 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
17240 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
17250 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
17260 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17270 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
17280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
17290 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
172a0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
172b0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
172c0 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
172d0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
172e0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
172f0 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
17300 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
17310 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
17320 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
17330 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
17340 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
17350 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
17360 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
17370 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
17380 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
17390 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
173a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
173b0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
173c0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
173d0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
173e0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
173f0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
17400 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
17410 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
17420 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
17430 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
17440 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
17450 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
17460 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
17470 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
17480 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
17490 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
174a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
174b0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
174c0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
174d0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
174e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
174f0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
17500 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
17510 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
17520 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
17530 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
17540 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
17550 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
17560 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
17570 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
17580 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
17590 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
175a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
175b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
175c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
175d0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
175e0 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
175f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17600 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17610 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
17620 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
17630 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
17640 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
17650 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
17660 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
17670 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
17680 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
17690 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
176a0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
176b0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
176c0 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
176d0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
176e0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
176f0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
17700 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
17710 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
17720 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17730 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
17740 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
17750 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
17760 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
17770 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
17780 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
17790 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
177a0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
177b0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
177c0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
177d0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
177e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
177f0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
17800 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
17810 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
17820 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
17830 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
17840 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
17850 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
17860 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
17870 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
17880 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
17890 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
178a0 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
178b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
178c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
178d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
178e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
178f0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
17900 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17910 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
17920 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17930 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
17940 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
17950 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
17960 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
17970 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
17980 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
17990 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
179a0 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
179b0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
179c0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
179d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
179e0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
179f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
17a00 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
17a10 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
17a20 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
17a30 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
17a40 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
17a50 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
17a60 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
17a70 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
17a80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17a90 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
17aa0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
17ab0 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
17ac0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
17ad0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
17ae0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
17af0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
17b00 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
17b10 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
17b20 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
17b30 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
17b40 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
17b50 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
17b60 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
17b70 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
17b80 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
17b90 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
17ba0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
17bb0 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
17bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17bd0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
17be0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17bf0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
17c00 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
17c10 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
17c20 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
17c30 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
17c40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
17c50 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
17c60 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
17c70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
17c80 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
17c90 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
17ca0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17cb0 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
17cc0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
17cd0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
17ce0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17cf0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
17d00 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
17d10 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
17d20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17d30 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
17d40 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
17d50 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
17d60 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
17d70 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
17d80 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
17d90 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
17da0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
17db0 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
17dc0 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
17dd0 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
17de0 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
17df0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
17e00 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
17e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17e20 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
17e30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
17e40 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
17e50 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
17e60 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
17e70 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
17e80 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
17e90 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
17ea0 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
17eb0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
17ec0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
17ed0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
17ee0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
17ef0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
17f00 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
17f10 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
17f20 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
17f30 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
17f40 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
17f50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17f60 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
17f70 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
17f80 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
17f90 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
17fa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
17fb0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
17fc0 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
17fd0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
17fe0 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
17ff0 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
18000 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
18010 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
18020 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
18030 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
18040 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
18050 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
18060 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
18070 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
18080 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
18090 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
180a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
180b0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
180c0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
180d0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
180e0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
180f0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
18100 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
18110 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
18120 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
18130 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18140 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
18150 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
18160 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18170 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
18180 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
18190 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
181a0 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
181b0 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
181c0 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
181d0 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
181e0 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
181f0 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
18200 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
18210 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
18220 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
18230 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
18240 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
18250 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
18260 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
18270 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
18280 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18290 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
182a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
182b0 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
182c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
182d0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
182e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
182f0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
18300 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
18310 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18320 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
18330 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
18340 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
18350 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
18360 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
18370 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
18380 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
18390 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
183a0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
183b0 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
183c0 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
183d0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
183e0 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
183f0 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
18400 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
18410 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18420 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
18430 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
18440 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
18450 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
18460 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
18470 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
18480 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
18490 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
184a0 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
184b0 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
184c0 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
184d0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
184e0 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
184f0 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
18500 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
18510 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
18520 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18530 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
18540 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18550 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
18560 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
18570 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
18580 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
18590 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
185a0 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
185b0 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
185c0 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
185d0 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
185e0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
185f0 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
18600 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
18610 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
18620 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
18630 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
18640 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
18650 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
18660 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  e..** </dl>.*/.#
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 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
18690 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
186a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
186b0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
186c0 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
186d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
186e0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
186f0 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
18700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18710 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
18720 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
18730 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
18740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
18760 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
18770 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
18780 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
18790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
187a0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
187b0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
187c0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
187d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
187e0 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
187f0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18800 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18810 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18820 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
18830 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
18840 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
18850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18860 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
18870 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
18880 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
18890 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
188a0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
188b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
188c0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
188d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
188e0 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
188f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18900 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
18910 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
18920 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
18930 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
18940 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
18950 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18960 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18970 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
18980 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
18990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
189a0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
189b0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
189c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
189d0 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
189e0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
189f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a00 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
18a10 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
18a20 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
18a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
18a40 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
18a50 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
18a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18a70 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
18a80 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
18a90 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18ab0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
18ac0 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
18ad0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
18ae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18af0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
18b00 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
18b10 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18b20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18b30 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
18b40 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
18b50 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
18b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
18b70 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
18b80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
18b90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
18ba0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18bb0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
18bc0 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
18bd0 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
18be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18bf0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
18c00 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
18c10 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
18c20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18c30 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
18c40 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
18c50 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
18c60 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18c70 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
18c80 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
18c90 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
18ca0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
18cb0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
18cc0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
18cd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18ce0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
18cf0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
18d00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18d10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
18d20 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
18d30 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
18d40 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
18d50 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
18d60 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
18d70 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
18d80 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
18d90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18da0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
18db0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
18dc0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
18dd0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
18de0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
18df0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
18e00 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
18e10 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
18e20 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
18e30 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
18e40 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
18e50 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
18e60 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
18e70 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
18e80 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
18e90 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
18ea0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
18eb0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
18ec0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
18ed0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ee0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
18ef0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18f00 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
18f10 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18f20 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
18f30 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
18f40 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
18f50 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
18f60 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
18f70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18f80 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
18f90 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
18fa0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18fb0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
18fc0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
18fd0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
18fe0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
18ff0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
19000 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
19010 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19020 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
19030 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
19040 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
19050 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
19060 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
19070 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
19080 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
19090 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
190a0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
190b0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
190c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
190d0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
190e0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
190f0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
19100 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
19110 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
19120 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
19130 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
19140 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
19150 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
19160 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
19170 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
19180 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
19190 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
191a0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
191b0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
191c0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
191d0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
191e0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
191f0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
19200 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
19210 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
19220 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
19230 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
19240 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
19250 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
19260 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
19270 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
19280 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
19290 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
192a0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
192b0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
192c0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
192d0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
192e0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
192f0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
19300 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
19310 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
19320 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
19330 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
19340 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
19350 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
19360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
19370 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
19380 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
19390 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
193a0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
193b0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
193c0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
193d0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
193e0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
193f0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
19400 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
19410 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
19420 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
19430 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
19440 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19450 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
19460 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19470 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
19480 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
19490 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
194a0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
194b0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
194c0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
194d0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
194e0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
194f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19500 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19510 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19520 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19530 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
19540 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
19550 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
19560 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
19570 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
19580 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
19590 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
195a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
195b0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
195c0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
195d0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
195e0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
195f0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19600 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19610 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19620 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19630 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19650 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19660 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
19670 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
19680 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
19690 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
196a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
196b0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
196c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
196d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
196e0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
196f0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
19700 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19710 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
19720 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
19730 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
19740 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
19750 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
19760 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
19770 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
19780 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
19790 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
197a0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
197b0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
197c0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
197d0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
197e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
197f0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19800 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19810 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19820 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19830 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
19840 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
19850 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
19860 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
19870 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
19880 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
19890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
198a0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
198b0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
198c0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
198d0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
198e0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
198f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19900 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
19910 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
19920 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
19930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19940 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19950 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
19960 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19970 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19980 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
19990 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
199a0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
199b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
199c0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
199d0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
199e0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
199f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19a00 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19a10 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19a20 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
19a30 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
19a40 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
19a50 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
19a60 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
19a70 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
19a80 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
19a90 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19aa0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19ab0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19ac0 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
19ad0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
19ae0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74  CALL sqlite3_ext
19af0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
19b00 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
19b10 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
19b20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
19b30 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
19b40 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19b50 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
19b60 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
19b70 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
19b80 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
19b90 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
19ba0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
19bb0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
19bc0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
19bd0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
19be0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
19bf0 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
19c00 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
19c10 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
19c20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
19c30 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
19c40 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
19c50 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
19c60 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
19c70 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
19c80 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
19c90 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
19ca0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
19cb0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
19cc0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
19cd0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
19ce0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
19cf0 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
19d00 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
19d10 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
19d30 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
19d40 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
19d50 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
19d60 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
19d70 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
19d80 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
19d90 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
19da0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
19db0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
19dc0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19dd0 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
19de0 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
19df0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19e00 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19e10 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
19e20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
19e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19e40 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
19e50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
19e60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19e70 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
19e80 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
19e90 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
19ea0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
19eb0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
19ec0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
19ed0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
19ee0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
19ef0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
19f00 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
19f10 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
19f20 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
19f30 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
19f40 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
19f50 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
19f60 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
19f70 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
19f80 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
19f90 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
19fa0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
19fb0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
19fc0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
19fd0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
19fe0 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
19ff0 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
1a000 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1a010 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1a020 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1a030 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1a040 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1a050 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1a060 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1a070 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a080 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1a090 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1a0a0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1a0b0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1a0c0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1a0d0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1a0e0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1a0f0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1a100 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a110 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1a120 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1a130 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1a140 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1a150 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1a160 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1a170 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1a180 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1a190 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1a1a0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1a1b0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1a1c0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1a1d0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1a1e0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1a1f0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a200 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1a210 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1a220 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a230 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1a240 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1a250 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1a260 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1a270 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1a280 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1a290 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1a2a0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1a2b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1a2c0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1a2d0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1a2e0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1a2f0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1a300 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a310 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a320 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a330 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1a340 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1a350 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1a360 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1a370 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1a380 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1a390 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1a3a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1a3b0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1a3c0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1a3d0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1a3e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1a3f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1a400 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a410 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1a420 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1a430 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1a440 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1a450 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1a460 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1a470 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
1a480 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1a490 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1a4a0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1a4b0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1a4c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a4d0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
1a4e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1a4f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1a500 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a510 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1a520 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1a530 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1a540 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
1a550 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1a560 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1a570 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
1a580 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a590 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1a5a0 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
1a5b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
1a5c0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
1a5d0 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
1a5e0 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1a5f0 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1a600 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
1a610 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
1a620 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1a630 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1a640 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
1a650 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
1a660 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
1a670 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a680 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a690 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
1a6a0 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
1a6b0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1a6c0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
1a6d0 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
1a6e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1a6f0 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
1a700 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
1a710 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
1a720 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1a730 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
1a740 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a750 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
1a760 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1a770 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
1a780 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
1a790 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
1a7a0 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
1a7b0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1a7c0 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
1a7d0 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
1a7e0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a7f0 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
1a800 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
1a810 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
1a820 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
1a830 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
1a840 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
1a850 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
1a860 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
1a870 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
1a880 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a890 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
1a8a0 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
1a8b0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a8c0 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
1a8d0 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
1a8e0 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
1a8f0 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
1a900 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
1a910 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
1a920 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
1a930 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
1a940 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a950 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
1a960 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
1a970 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
1a980 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
1a990 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a9a0 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
1a9b0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1a9c0 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
1a9d0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
1a9e0 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
1a9f0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1aa00 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
1aa10 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
1aa20 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
1aa30 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
1aa40 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
1aa50 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
1aa60 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
1aa70 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
1aa80 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
1aa90 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
1aaa0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1aab0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1aac0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1aad0 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
1aae0 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
1aaf0 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
1ab00 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
1ab10 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
1ab20 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
1ab30 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
1ab40 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
1ab50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1ab60 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
1ab70 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
1ab80 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
1ab90 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
1aba0 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
1abb0 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
1abc0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
1abd0 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
1abe0 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
1abf0 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
1ac00 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
1ac10 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1ac20 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1ac30 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1ac40 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
1ac50 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
1ac60 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
1ac70 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
1ac80 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
1ac90 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
1aca0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1acb0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
1acc0 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
1acd0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
1ace0 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
1acf0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
1ad00 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
1ad10 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1ad20 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
1ad30 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
1ad40 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1ad50 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1ad60 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
1ad70 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
1ad80 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1ad90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1ada0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1adb0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1adc0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1add0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1ade0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1adf0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1ae00 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1ae10 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1ae20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ae30 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1ae40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ae50 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1ae60 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1ae70 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1ae80 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1ae90 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1aea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1aeb0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1aec0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1aed0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1aee0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1aef0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1af00 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1af10 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1af20 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1af30 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
1af40 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
1af50 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
1af60 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
1af70 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
1af80 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
1af90 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1afa0 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
1afb0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
1afc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1afd0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
1afe0 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
1aff0 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
1b000 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
1b010 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
1b020 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1b030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1b040 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
1b050 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1b060 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1b070 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
1b080 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
1b090 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1b0a0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1b0b0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
1b0c0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
1b0d0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
1b0e0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
1b0f0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
1b100 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1b110 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
1b120 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1b130 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1b140 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
1b150 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
1b160 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1b170 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b180 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1b190 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b1a0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b1b0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b1c0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1b1d0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b1e0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b1f0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b200 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b210 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b220 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b230 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b240 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b250 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1b260 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1b270 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1b280 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1b290 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1b2a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b2b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1b2c0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b2d0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1b2e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b2f0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1b300 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1b310 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b320 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1b330 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1b340 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1b350 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1b360 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1b370 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1b380 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1b390 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1b3a0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1b3b0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1b3c0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1b3d0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1b3e0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1b3f0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1b400 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1b410 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1b420 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1b430 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1b440 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1b450 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1b460 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1b470 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1b480 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1b490 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1b4a0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1b4b0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1b4c0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1b4d0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1b4e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b4f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1b500 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1b510 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1b520 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1b530 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1b540 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1b550 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1b560 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1b570 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1b580 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1b590 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1b5a0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1b5b0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1b5c0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1b5d0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1b5e0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1b5f0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1b600 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1b610 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1b620 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1b630 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1b640 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1b650 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1b660 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1b670 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1b680 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1b690 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1b6a0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1b6b0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1b6c0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1b6d0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1b6e0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1b6f0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1b700 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1b710 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b720 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1b730 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1b740 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1b750 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1b760 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1b770 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1b780 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1b790 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1b7a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b7b0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b7c0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1b7d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b7e0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1b7f0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1b800 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1b810 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1b820 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1b830 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1b840 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1b850 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1b860 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1b870 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1b880 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1b890 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1b8a0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1b8b0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1b8c0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1b8d0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1b8e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b8f0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1b900 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1b910 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1b920 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1b930 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1b940 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b950 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1b960 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1b970 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1b980 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b990 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b9a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b9b0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1b9c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1b9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b9e0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1b9f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ba00 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1ba10 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1ba20 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1ba30 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1ba40 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1ba50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1ba60 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1ba70 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ba80 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1ba90 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1baa0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1bab0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1bac0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1bad0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1bae0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1baf0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1bb00 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1bb10 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1bb20 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1bb30 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1bb40 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1bb50 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1bb60 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1bb70 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1bb80 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1bb90 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1bba0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bbb0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1bbc0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1bbd0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1bbe0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1bbf0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1bc00 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1bc10 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1bc20 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1bc30 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1bc40 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1bc50 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1bc60 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1bc70 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1bc80 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1bc90 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1bca0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1bcb0 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1bcc0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1bcd0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1bce0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1bcf0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1bd00 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1bd10 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1bd20 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1bd30 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1bd40 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1bd50 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1bd60 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1bd70 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1bd80 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1bd90 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1bda0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1bdb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1bdc0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bdd0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1bde0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1bdf0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1be00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1be10 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1be20 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1be30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1be40 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1be50 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1be60 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1be70 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1be80 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1be90 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1bea0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1beb0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1bec0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1bed0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1bee0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1bef0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1bf00 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1bf10 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1bf20 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1bf30 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1bf40 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1bf50 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1bf60 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1bf70 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1bf80 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1bf90 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1bfa0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1bfb0 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1bfc0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1bfd0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1bfe0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1bff0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1c000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1c010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1c020 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1c030 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c040 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1c050 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1c060 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1c070 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1c080 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1c090 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1c0a0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1c0b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1c0c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1c0d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1c0e0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c0f0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1c100 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1c110 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1c120 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c130 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1c140 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1c150 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1c160 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1c170 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1c180 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
1c190 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
1c1a0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
1c1b0 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d  sy handler}.** M
1c1c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c1d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c1e0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
1c1f0 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
1c200 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1c210 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
1c220 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1c230 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
1c240 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
1c250 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1c260 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
1c270 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
1c280 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
1c290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c2a0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
1c2b0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1c2c0 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
1c2d0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
1c2e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
1c2f0 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
1c300 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
1c310 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
1c320 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1c330 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
1c340 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c350 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
1c360 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1c370 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1c380 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
1c390 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1c3a0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1c3b0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1c3c0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1c3d0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1c3e0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1c3f0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1c400 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1c410 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1c420 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1c430 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1c440 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c450 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1c460 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1c470 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1c480 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1c490 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c4a0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1c4b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1c4c0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c4d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1c4e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1c4f0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1c500 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1c510 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1c520 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1c530 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1c540 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1c550 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1c560 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1c570 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1c580 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1c590 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1c5a0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1c5b0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1c5c0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1c5d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1c5e0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1c5f0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1c600 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1c610 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1c620 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1c630 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1c640 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1c650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1c660 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1c670 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1c680 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1c690 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1c6a0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1c6b0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1c6c0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1c6d0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1c6e0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1c6f0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1c700 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1c710 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1c720 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1c730 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1c740 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1c750 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1c760 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1c770 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1c780 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1c790 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1c7a0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1c7b0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1c7c0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1c7d0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1c7e0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1c7f0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1c800 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1c810 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1c820 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1c830 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1c840 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1c850 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1c860 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1c870 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1c880 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1c890 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1c8a0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1c8b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1c8c0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1c8d0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c8e0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1c8f0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1c900 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1c910 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c920 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1c930 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1c940 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1c950 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1c960 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1c970 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1c980 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1c990 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1c9a0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1c9b0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1c9c0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1c9d0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1c9e0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1c9f0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1ca00 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1ca10 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1ca20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1ca30 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1ca40 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1ca50 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1ca60 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1ca70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ca80 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1ca90 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1caa0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1cab0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1cac0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1cad0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1cae0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1caf0 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1cb00 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1cb10 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1cb20 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1cb30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1cb40 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1cb50 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1cb60 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1cb70 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1cb80 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1cb90 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1cba0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1cbb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1cbc0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1cbd0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1cbe0 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1cbf0 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1cc00 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1cc10 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1cc20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1cc30 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1cc40 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1cc50 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1cc60 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1cc70 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1cc80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1cc90 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1cca0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1ccb0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1ccc0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1ccd0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1cce0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1ccf0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1cd00 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1cd10 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1cd20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cd30 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1cd40 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1cd50 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1cd60 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1cd70 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1cd80 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1cd90 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1cda0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1cdb0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1cdc0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1cdd0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1cde0 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1cdf0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1ce00 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1ce10 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1ce20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1ce30 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1ce40 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1ce50 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1ce60 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1ce70 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1ce80 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1ce90 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1cea0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1ceb0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1cec0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1ced0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1cee0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1cef0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1cf00 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1cf10 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1cf20 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1cf30 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1cf40 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1cf50 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1cf60 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1cf70 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1cf80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cf90 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1cfa0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1cfb0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1cfc0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1cfd0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1cfe0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1cff0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1d000 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1d010 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1d020 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1d030 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1d040 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1d050 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1d060 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
1d070 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1d080 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  LL sqlite3_busy_
1d090 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1d0a0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1d0b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1d0c0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1d0d0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1d0e0 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1d0f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1d100 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1d110 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1d120 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1d130 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1d140 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1d150 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1d160 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1d170 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1d180 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1d190 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1d1a0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1d1b0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1d1c0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d1d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1d1e0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1d1f0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1d200 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1d210 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1d220 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1d230 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1d240 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1d250 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1d260 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1d270 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1d280 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1d290 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1d2a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1d2b0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1d2c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1d2d0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1d2e0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1d2f0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1d300 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1d310 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1d320 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1d330 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1d340 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1d350 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1d360 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1d370 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1d380 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1d390 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1d3a0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1d3b0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1d3c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1d3d0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1d3e0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1d3f0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1d400 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1d410 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1d420 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1d430 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1d440 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1d450 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1d460 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1d470 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1d480 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1d490 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1d4a0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1d4b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1d4c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1d4d0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1d4e0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1d4f0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1d500 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1d510 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1d520 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1d530 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1d540 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1d550 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1d560 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1d570 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1d580 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1d590 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d5a0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1d5b0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1d5c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d5d0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1d5e0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1d5f0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1d600 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d610 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1d620 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1d630 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1d640 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d650 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1d660 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1d670 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1d680 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1d690 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1d6a0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1d6b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1d6c0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1d6d0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1d6e0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1d6f0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1d700 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1d710 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1d720 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1d730 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1d740 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1d750 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1d760 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1d770 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1d780 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1d790 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d7a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d7b0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1d7c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d7d0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1d7e0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1d7f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1d800 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1d810 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d820 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1d830 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d840 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1d850 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d860 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1d870 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d880 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1d890 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1d8a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1d8b0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1d8c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1d8d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1d8e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d8f0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1d900 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1d910 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1d920 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1d930 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1d940 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1d950 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1d960 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1d970 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1d980 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1d990 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1d9a0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1d9b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1d9c0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1d9d0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1d9e0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1d9f0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1da00 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1da10 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1da20 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1da30 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1da40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1da50 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1da60 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1da70 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1da80 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1da90 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1daa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dab0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1dac0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1dad0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1dae0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1daf0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1db00 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1db10 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1db20 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1db30 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1db40 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1db50 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1db60 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1db70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1db80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1db90 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1dba0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1dbb0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1dbc0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1dbd0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1dbe0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1dbf0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1dc00 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1dc10 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1dc20 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1dc30 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1dc40 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1dc50 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1dc60 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1dc70 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1dc80 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1dc90 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1dca0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1dcb0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1dcc0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1dcd0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1dce0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1dcf0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1dd00 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1dd10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1dd20 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1dd30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1dd40 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1dd50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1dd60 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1dd70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1dd80 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1dd90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1dda0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1ddb0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1ddc0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1ddd0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1dde0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1ddf0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1de00 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1de10 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1de20 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1de30 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1de40 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1de50 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1de60 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1de70 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1de80 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1de90 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1dea0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1deb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1dec0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
1ded0 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  L sqlite3_free_t
1dee0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1def0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1df00 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1df10 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1df20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1df30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1df40 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1df50 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1df60 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1df70 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1df80 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1df90 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1dfa0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1dfb0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1dfc0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1dfd0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1dfe0 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1dff0 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1e000 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1e010 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1e020 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1e030 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1e040 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e050 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1e060 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1e070 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1e080 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1e090 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1e0a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e0b0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1e0c0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1e0d0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1e0e0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1e0f0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1e100 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1e110 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1e120 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1e130 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1e140 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1e150 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1e160 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1e170 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1e180 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1e190 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1e1a0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1e1b0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1e1c0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1e1d0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1e1e0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1e1f0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1e200 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1e210 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1e220 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1e230 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1e240 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1e250 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1e260 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1e270 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1e280 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1e290 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1e2a0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1e2b0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1e2c0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1e2d0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1e2e0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1e2f0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1e300 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1e310 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1e320 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1e330 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1e340 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1e350 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1e360 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1e370 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1e380 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1e390 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1e3a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1e3b0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1e3c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1e3d0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1e3e0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1e3f0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1e400 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1e410 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1e420 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1e430 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1e440 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1e450 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1e460 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1e470 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1e480 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1e490 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1e4a0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1e4b0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1e4c0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1e4d0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1e4e0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1e4f0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1e500 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1e510 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1e520 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1e530 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1e540 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1e550 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1e560 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1e570 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1e580 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1e590 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1e5a0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1e5b0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1e5c0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1e5d0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1e5e0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1e5f0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1e600 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1e610 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1e620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e630 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1e640 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1e650 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1e660 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e670 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1e680 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1e690 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1e6a0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1e6b0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1e6c0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1e6d0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1e6e0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1e6f0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1e700 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1e710 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1e720 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1e730 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1e740 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1e750 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1e760 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1e770 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1e780 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1e790 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1e7a0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1e7b0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1e7c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1e7d0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1e7e0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1e7f0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1e800 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1e810 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1e820 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1e830 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1e840 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1e850 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1e860 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1e870 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1e880 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1e890 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1e8a0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1e8b0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1e8c0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1e8d0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1e8e0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1e8f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e900 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e910 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1e920 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1e930 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e940 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1e950 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1e960 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1e970 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1e980 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e990 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e9a0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e9b0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1e9c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1e9d0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1e9e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e9f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1ea00 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1ea10 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1ea20 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ea30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1ea40 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1ea50 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1ea60 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1ea70 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1ea80 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1ea90 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1eaa0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1eab0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1eac0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ead0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1eae0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1eaf0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1eb00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1eb10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1eb20 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1eb30 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1eb40 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1eb50 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1eb60 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1eb70 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1eb80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1eb90 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1eba0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1ebb0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1ebc0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1ebd0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1ebe0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1ebf0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1ec00 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1ec10 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1ec20 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1ec30 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1ec40 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1ec50 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1ec60 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1ec70 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1ec80 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1ec90 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1eca0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1ecb0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1ecc0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1ecd0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1ece0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1ecf0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1ed00 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1ed10 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1ed20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1ed30 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1ed40 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1ed50 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1ed60 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1ed70 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1ed80 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1ed90 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1eda0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1edb0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1edc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1edd0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1ede0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1edf0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1ee00 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1ee10 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1ee20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1ee30 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1ee40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1ee50 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1ee60 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1ee70 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1ee80 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1ee90 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1eea0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1eeb0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1eec0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1eed0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1eee0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1eef0 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1ef00 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1ef10 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1ef20 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1ef30 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1ef40 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1ef50 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1ef60 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1ef70 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1ef80 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1ef90 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1efa0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1efb0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1efc0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1efd0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1efe0 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1eff0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1f000 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1f010 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1f020 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1f030 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1f040 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1f050 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1f060 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1f070 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1f080 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1f090 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1f0a0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1f0b0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1f0c0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1f0d0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1f0e0 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
1f0f0 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1f100 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d  _CDECL sqlite3_m
1f110 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f120 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1f130 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1f140 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1f150 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1f160 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1f170 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1f180 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73   *SQLITE_CDECL s
1f190 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1f1a0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1f1b0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1f1c0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1f1d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1f1e0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1f1f0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1f200 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1f210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f220 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1f230 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1f240 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1f250 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1f260 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1f270 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1f280 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1f290 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1f2a0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1f2b0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1f2c0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1f2d0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1f2e0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1f2f0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1f300 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1f310 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1f320 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1f330 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1f340 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1f350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f360 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1f370 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1f380 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1f390 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1f3a0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1f3b0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1f3c0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1f3d0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1f3e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1f3f0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1f400 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1f410 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1f420 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1f430 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1f440 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1f450 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f460 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1f470 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1f480 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1f490 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1f4a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1f4b0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1f4c0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1f4d0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1f4e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f4f0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1f500 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1f510 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1f520 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1f530 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1f540 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1f550 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1f560 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1f570 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1f580 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1f590 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1f5a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f5b0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1f5c0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1f5d0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1f5e0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1f5f0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1f600 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1f610 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1f620 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1f630 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1f640 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1f650 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1f660 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1f670 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1f680 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1f690 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1f6a0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1f6b0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1f6c0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1f6d0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1f6e0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1f6f0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1f700 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1f710 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1f720 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1f730 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1f740 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1f750 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1f760 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1f770 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1f780 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1f790 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1f7a0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1f7b0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1f7c0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1f7d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1f7e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f7f0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f800 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1f810 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1f820 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1f830 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1f840 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1f850 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1f860 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f870 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f880 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1f890 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1f8a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1f8b0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1f8c0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1f8d0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1f8e0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1f8f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1f900 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1f910 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1f920 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1f930 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1f940 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1f950 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1f960 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1f970 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1f980 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f990 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1f9a0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1f9b0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1f9c0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1f9d0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1f9e0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1f9f0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1fa00 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1fa10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1fa20 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1fa30 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1fa40 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1fa50 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1fa60 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1fa70 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1fa80 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1fa90 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1faa0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1fab0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1fac0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1fad0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1fae0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1faf0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1fb00 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1fb10 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1fb20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1fb30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1fb40 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1fb50 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1fb60 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1fb70 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1fb80 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1fb90 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1fba0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1fbb0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1fbc0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1fbd0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1fbe0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fbf0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1fc00 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1fc10 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1fc20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1fc30 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1fc40 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1fc50 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1fc60 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1fc70 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1fc80 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1fc90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1fca0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1fcb0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1fcc0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1fcd0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1fce0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1fcf0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1fd00 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1fd10 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1fd20 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1fd30 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1fd40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1fd50 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1fd60 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1fd70 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1fd80 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1fd90 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1fda0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1fdb0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1fdc0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1fdd0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1fde0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1fdf0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1fe00 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1fe10 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1fe20 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1fe30 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1fe40 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1fe50 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1fe60 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1fe70 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1fe80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1fe90 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1fea0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1feb0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1fec0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1fed0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1fee0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1fef0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1ff00 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1ff10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1ff20 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1ff30 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1ff40 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1ff50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1ff60 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1ff70 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1ff80 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1ff90 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1ffa0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1ffb0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1ffc0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1ffd0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1ffe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1fff0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
20000 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
20010 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
20020 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
20030 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
20040 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20050 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
20060 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
20070 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
20080 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
20090 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
200a0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
200b0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
200c0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
200d0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
200e0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
200f0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
20100 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
20110 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
20120 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
20130 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
20140 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
20150 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
20160 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
20170 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
20180 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
20190 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
201a0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
201b0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
201c0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
201d0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
201e0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
201f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20200 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
20210 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
20220 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
20230 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
20240 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20250 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
20260 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
20270 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
20280 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
20290 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
202a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
202b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
202c0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
202d0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
202e0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
202f0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
20300 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
20310 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
20320 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
20330 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
20340 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
20350 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
20360 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
20370 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20380 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
20390 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
203a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
203b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
203c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
203d0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
203e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
203f0 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
20400 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
20410 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
20420 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  LL sqlite3_reall
20430 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
20440 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
20450 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
20460 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
20470 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
20480 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
20490 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
204a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
204b0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51  _free(void*);.SQ
204c0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
204d0 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  _uint64 SQLITE_S
204e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
204f0 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
20500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
20510 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
20520 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
20530 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
20540 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
20550 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
20560 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
20570 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
20580 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
20590 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
205a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
205b0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
205c0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
205d0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
205e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
205f0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
20600 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20610 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
20620 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
20630 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
20640 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
20650 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
20660 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
20670 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
20680 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
20690 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
206a0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
206b0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
206c0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
206d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
206e0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
206f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
20700 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
20710 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
20720 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20730 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20740 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
20750 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20760 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
20770 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
20780 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
20790 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
207a0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
207b0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
207c0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
207d0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
207e0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
207f0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
20800 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
20810 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
20820 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
20830 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
20840 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
20850 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
20860 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
20870 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20880 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
20890 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
208a0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
208b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
208c0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
208d0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
208e0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
208f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20900 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
20910 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
20920 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
20930 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
20940 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
20950 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
20960 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
20970 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
20980 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
20990 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
209a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
209b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
209c0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
209d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
209e0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
209f0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20a00 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20a10 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20a20 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
20a30 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
20a40 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
20a50 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
20a60 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
20a70 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
20a80 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
20a90 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
20aa0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
20ab0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
20ac0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
20ad0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
20ae0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
20af0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
20b00 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
20b10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
20b20 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
20b30 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
20b40 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
20b50 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
20b60 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
20b70 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
20b80 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20b90 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
20ba0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
20bb0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
20bc0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
20bd0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
20be0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20bf0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
20c00 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
20c10 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
20c20 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
20c30 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
20c40 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
20c50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20c60 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
20c70 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
20c80 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
20c90 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
20ca0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
20cb0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
20cc0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20cd0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
20ce0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
20cf0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
20d00 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
20d10 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
20d20 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
20d30 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
20d40 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
20d50 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
20d60 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
20d70 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
20d80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
20d90 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
20da0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
20db0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
20dc0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
20dd0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
20de0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
20df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e00 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
20e10 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
20e20 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
20e30 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
20e40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
20e50 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
20e60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
20e70 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
20e80 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
20e90 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
20ea0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
20eb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20ec0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20ed0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20ee0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
20ef0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
20f00 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
20f10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20f20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
20f30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20f40 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
20f50 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
20f60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
20f70 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
20f80 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
20f90 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
20fa0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
20fb0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
20fc0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
20fd0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
20fe0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
20ff0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21000 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21010 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
21020 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
21030 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
21040 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21050 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
21060 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
21070 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
21080 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
21090 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
210a0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
210b0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
210c0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
210d0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
210e0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
210f0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
21100 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
21110 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
21120 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
21130 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
21140 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
21150 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21160 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
21170 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
21180 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
21190 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
211a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
211b0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
211c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
211d0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
211e0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
211f0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
21200 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
21210 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
21220 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
21230 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
21240 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21250 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
21260 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
21270 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
21280 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
21290 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
212a0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
212b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
212c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
212d0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
212e0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
212f0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
21300 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
21310 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
21320 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
21330 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
21340 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
21350 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
21360 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
21370 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21380 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
21390 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
213a0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
213b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
213c0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
213d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
213e0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
213f0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21400 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
21410 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
21420 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
21430 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
21440 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
21450 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
21460 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
21470 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
21480 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
21490 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
214a0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
214b0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
214c0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
214d0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
214e0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
214f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
21500 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21510 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
21520 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
21530 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
21540 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
21550 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
21560 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
21570 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
21580 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
21590 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
215a0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
215b0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
215c0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
215d0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
215e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
215f0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
21600 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
21610 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
21620 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
21630 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
21640 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
21650 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
21660 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
21670 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
21680 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
21690 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
216a0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
216b0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
216c0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
216d0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
216e0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
216f0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
21700 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
21710 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
21720 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
21730 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
21740 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
21750 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
21760 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
21770 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
21780 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
21790 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
217a0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
217b0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
217c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
217d0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
217e0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
217f0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
21800 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
21810 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
21820 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
21830 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
21840 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
21850 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
21860 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
21870 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
21880 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
21890 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
218a0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
218b0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
218c0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
218d0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
218e0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
218f0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
21900 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
21910 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
21920 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
21930 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
21940 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
21950 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
21960 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
21970 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
21980 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
21990 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
219a0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
219b0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
219c0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
219d0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
219e0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
219f0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
21a00 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
21a10 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
21a20 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
21a30 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
21a40 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
21a50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
21a60 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
21a70 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
21a80 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
21a90 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21aa0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
21ab0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
21ac0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
21ad0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
21ae0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
21af0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
21b00 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
21b10 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
21b20 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
21b30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
21b40 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
21b50 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
21b60 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
21b70 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
21b80 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
21b90 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
21ba0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
21bb0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
21bc0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
21bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
21be0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21bf0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
21c00 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
21c10 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
21c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21c30 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
21c40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21c50 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
21c60 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
21c70 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21c80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21c90 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21ca0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21cb0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
21cc0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
21cd0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
21ce0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
21cf0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
21d00 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
21d10 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
21d20 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
21d30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
21d40 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
21d50 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
21d60 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
21d70 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
21d80 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
21d90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
21da0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
21db0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
21dc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21dd0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
21de0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
21df0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e00 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
21e10 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
21e20 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
21e30 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
21e40 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
21e50 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
21e60 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
21e70 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
21e80 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
21e90 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
21ea0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
21eb0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
21ec0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
21ed0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
21ee0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
21ef0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
21f00 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
21f10 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
21f20 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
21f30 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
21f40 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
21f50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
21f60 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
21f70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21f80 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21f90 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21fa0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
21fb0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21fc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
21fd0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
21fe0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
21ff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22000 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
22010 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
22020 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
22030 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
22040 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22050 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
22060 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
22070 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
22080 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
22090 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
220a0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
220b0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
220c0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
220d0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
220e0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
220f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
22100 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
22110 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
22120 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
22130 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
22140 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
22150 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
22160 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
22170 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
22180 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
22190 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
221a0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
221b0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
221c0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
221d0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
221e0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
221f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22200 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
22210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22220 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
22230 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
22240 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
22250 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
22260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22270 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
22280 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
22290 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
222a0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
222b0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
222c0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
222d0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
222e0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
222f0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
22300 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
22310 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
22320 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
22330 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
22340 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
22350 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
22360 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
22370 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
22380 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
22390 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
223a0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
223b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
223c0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
223d0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
223e0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
223f0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
22400 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
22410 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
22420 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
22430 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
22440 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
22450 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
22460 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
22470 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
22480 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
22490 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
224a0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
224b0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
224c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
224d0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
224e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
224f0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
22500 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
22510 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
22520 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
22530 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
22540 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
22550 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
22560 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
22570 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
22580 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22590 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
225a0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
225b0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
225c0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
225d0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
225e0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
225f0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
22600 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
22610 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
22620 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
22630 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22640 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22650 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
22660 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
22670 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
22680 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
22690 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
226a0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
226b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
226c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
226d0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
226e0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
226f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22700 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22710 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22720 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
22730 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
22740 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22750 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22760 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22770 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
22780 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
22790 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
227a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
227b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
227c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
227d0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
227e0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
227f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22810 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
22820 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
22830 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22840 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22860 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
22870 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
22880 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22890 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
228a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
228b0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
228c0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
228d0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
228e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
228f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
22900 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
22910 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
22920 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22930 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22940 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22950 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22960 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
22970 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22980 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22990 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
229a0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
229b0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
229c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
229d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
229e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
229f0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
22a00 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
22a10 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22a20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22a30 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22a40 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
22a50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22a60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22a70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22a80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22a90 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
22aa0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22ab0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22ac0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ad0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22ae0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
22af0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22b00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22b10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b20 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
22b30 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
22b40 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22b50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22b60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22b70 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
22b80 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
22b90 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22ba0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22bb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22bc0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
22bd0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
22be0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22bf0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22c00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c10 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
22c20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
22c30 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
22c40 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
22c50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22c60 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
22c70 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
22c80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22c90 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22cb0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
22cc0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
22cd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
22ce0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d00 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
22d10 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
22d20 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
22d30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
22d50 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
22d60 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
22d70 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22d80 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22da0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22db0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
22dc0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
22dd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
22df0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22e00 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
22e10 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
22e20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
22e40 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
22e50 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
22e60 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
22e70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22e80 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22e90 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22ea0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22eb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22ec0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22ed0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
22ee0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
22ef0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22f00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22f10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22f20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22f30 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
22f40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22f50 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22f60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22f70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22f80 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22f90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22fa0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22fb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22fc0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
22fd0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
22fe0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22ff0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
23000 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
23010 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
23020 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
23030 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
23040 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
23050 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
23060 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
23070 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
23080 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
23090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
230a0 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
230b0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
230c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
230d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
230e0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
230f0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
23100 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
23110 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
23120 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
23130 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
23140 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
23150 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
23160 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
23170 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
23180 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
23190 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
231a0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
231b0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
231c0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
231d0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
231e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
231f0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
23200 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
23210 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
23220 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
23230 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
23240 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23250 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23260 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
23270 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
23280 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
23290 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
232a0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
232b0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
232c0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
232d0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
232e0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
232f0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
23300 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
23310 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
23320 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
23330 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
23340 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
23350 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
23360 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
23370 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
23380 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
23390 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
233a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
233b0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
233c0 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
233d0 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
233e0 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
233f0 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
23400 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
23410 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
23420 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
23430 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
23440 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
23450 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
23460 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
23470 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
23480 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
23490 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
234a0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
234b0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
234c0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
234d0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
234e0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
234f0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
23500 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
23510 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
23520 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
23530 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
23540 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
23550 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
23560 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
23570 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
23580 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
23590 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
235a0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
235b0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
235c0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
235d0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
235e0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
235f0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
23600 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
23610 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
23620 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
23630 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
23640 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
23650 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
23660 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
23670 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
23680 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
23690 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
236a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
236b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
236c0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
236d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
236e0 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
236f0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
23700 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
23710 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
23720 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
23730 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49  ENTAL void *SQLI
23740 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
23750 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
23760 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
23770 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
23780 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
23790 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
237a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
237b0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
237c0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
237d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
237e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
237f0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23800 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23810 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23820 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23830 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
23840 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
23850 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
23860 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
23870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
23880 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
23890 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
238a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
238b0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
238c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
238d0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
238e0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
238f0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23900 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23910 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23920 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23930 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
23940 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
23950 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
23960 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
23970 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
23980 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
23990 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
239a0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
239b0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
239c0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
239d0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
239e0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
239f0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
23a00 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
23a10 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
23a20 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
23a30 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
23a40 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
23a50 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
23a60 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
23a70 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
23a80 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
23a90 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
23aa0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
23ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
23ac0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
23ad0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
23ae0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
23af0 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
23b00 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
23b10 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
23b20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23b30 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
23b40 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
23b50 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
23b60 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
23b70 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
23b80 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
23b90 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
23ba0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
23bb0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
23bc0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
23bd0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
23be0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
23bf0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
23c00 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
23c10 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
23c20 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
23c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
23c40 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
23c50 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
23c60 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
23c70 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
23c80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23c90 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
23ca0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
23cb0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
23cc0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
23cd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23ce0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23cf0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
23d00 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
23d10 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
23d20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
23d30 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
23d40 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
23d50 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
23d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
23d70 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23d80 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
23d90 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
23da0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
23db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23dc0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
23dd0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
23de0 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
23df0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23e00 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23e10 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23e20 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23e30 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23e40 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
23e50 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
23e60 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
23e70 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23e80 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
23e90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23ea0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23eb0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23ec0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23ed0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23ef0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23f10 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23f20 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23f30 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23f40 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23f50 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23f60 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23f70 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23f80 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23f90 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23fa0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23fb0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
23fc0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
23fd0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
23fe0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
23ff0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
24000 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
24010 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24020 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
24030 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
24040 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
24050 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
24060 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
24070 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
24080 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
24090 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
240a0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
240b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
240c0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
240d0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
240e0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
240f0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
24100 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
24110 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
24120 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
24130 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
24140 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
24150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
24160 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
24170 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
24180 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
24190 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
241a0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
241b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
241c0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
241d0 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
241e0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
241f0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
24200 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
24210 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24220 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
24230 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
24240 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
24250 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
24260 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
24270 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
24280 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
24290 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
242a0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
242b0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
242c0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
242d0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
242e0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
242f0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
24300 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
24310 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
24320 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
24330 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
24340 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
24350 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
24360 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
24370 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
24380 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
24390 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
243a0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
243b0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
243c0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
243d0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
243e0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
243f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
24400 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
24410 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24420 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
24430 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
24440 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
24450 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
24460 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24470 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
24480 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24490 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
244a0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
244b0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
244c0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
244d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
244e0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
244f0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24500 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24510 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24520 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24530 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24540 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24550 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24560 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24570 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24580 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
24590 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
245a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
245b0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
245c0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
245d0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
245e0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
245f0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24600 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24610 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24620 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24630 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24640 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24650 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
24660 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24670 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24680 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24690 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
246a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
246b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
246c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
246d0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
246e0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
246f0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24700 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24710 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24720 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24730 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24740 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24750 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24760 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
24770 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
24780 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
24790 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
247a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
247b0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
247c0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
247d0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
247e0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
247f0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24800 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24810 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24820 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24830 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24840 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24850 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
24860 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24870 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
24880 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24890 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
248a0 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
248b0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
248c0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
248d0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
248e0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
248f0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24900 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24910 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24920 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24930 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24940 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24950 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24960 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
24970 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
24980 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24990 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
249a0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
249b0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
249c0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
249d0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
249e0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
249f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24a00 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24a10 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24a20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24a30 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
24a40 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
24a50 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
24a60 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24a70 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
24a80 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
24a90 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
24aa0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
24ab0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
24ac0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24ad0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
24ae0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24b00 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24b10 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24b20 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24b30 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
24b40 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24b50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24b60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24b70 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
24b80 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
24b90 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
24ba0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
24bb0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24bc0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24bd0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
24be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24bf0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24c00 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24c10 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24c20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24c30 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
24c40 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24c50 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
24c60 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24c70 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
24c80 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
24c90 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
24ca0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
24cb0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
24cc0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
24cd0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
24ce0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24cf0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24d00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24d10 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24d20 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24d30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24d40 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24d50 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24d60 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24d70 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24d80 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
24d90 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
24da0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
24db0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24dc0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
24dd0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
24de0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24df0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24e00 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24e10 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24e20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24e30 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24e40 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24e50 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24e60 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24e70 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24e80 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
24e90 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24ea0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24eb0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24ec0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24ed0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24ee0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24ef0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24f00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24f10 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24f20 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24f30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24f40 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24f50 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24f60 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24f70 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24f80 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24f90 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24fa0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24fb0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24fc0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24fd0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24fe0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24ff0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
25000 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
25010 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
25020 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
25030 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
25040 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25050 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25060 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
25070 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
25080 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
25090 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
250a0 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
250b0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
250c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
250d0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
250e0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
250f0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
25100 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
25110 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25120 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
25130 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
25140 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
25150 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
25160 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
25170 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
25180 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
25190 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
251a0 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
251b0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
251c0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
251d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
251e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
251f0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
25200 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
25210 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
25220 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
25230 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
25240 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
25250 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
25260 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
25270 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
25280 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
25290 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
252a0 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
252b0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
252c0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
252d0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
252e0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
252f0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
25300 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
25310 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
25320 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
25330 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
25340 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
25350 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
25360 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25370 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
25380 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
25390 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
253a0 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
253b0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
253c0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
253d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
253e0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
253f0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
25400 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
25410 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25420 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
25430 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
25440 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
25450 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
25460 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
25470 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25480 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
25490 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
254a0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
254b0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
254c0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
254d0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
254e0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
254f0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
25500 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
25510 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
25520 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25530 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
25540 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
25550 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
25560 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
25570 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
25580 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
25590 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
255a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
255b0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
255c0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
255d0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
255e0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
255f0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
25600 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
25610 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
25620 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
25630 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
25640 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
25650 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
25660 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
25670 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
25680 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
25690 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
256a0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
256b0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
256c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
256d0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
256e0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
256f0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
25700 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
25710 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
25720 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
25730 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
25740 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
25750 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
25760 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25770 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
25780 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
25790 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
257a0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
257b0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
257c0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
257d0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
257e0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
257f0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
25800 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25810 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25820 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
25830 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
25840 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25850 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25860 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
25870 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
25880 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
25890 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
258a0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
258b0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
258c0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
258d0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
258e0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
258f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25900 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
25910 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
25920 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
25930 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25940 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
25950 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
25960 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
25970 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
25980 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
25990 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
259a0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
259b0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
259c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
259d0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
259e0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
259f0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
25a00 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
25a10 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
25a20 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
25a30 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
25a40 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
25a50 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
25a60 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
25a70 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
25a80 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25a90 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
25aa0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25ab0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
25ac0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25ad0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
25ae0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
25af0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25b00 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
25b10 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
25b20 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
25b30 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
25b40 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
25b50 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
25b60 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
25b70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
25b80 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
25b90 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
25ba0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
25bb0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
25bc0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
25bd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25be0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25bf0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
25c00 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
25c10 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
25c20 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25c30 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
25c40 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
25c50 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
25c60 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
25c70 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25c80 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
25c90 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25ca0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
25cb0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
25cc0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
25cd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25ce0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
25cf0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25d00 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
25d10 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
25d20 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
25d30 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
25d40 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
25d50 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
25d60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25d70 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
25d80 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
25d90 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
25da0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
25db0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
25dc0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
25dd0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
25de0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25df0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25e00 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25e10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25e20 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
25e30 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
25e40 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
25e50 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
25e60 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
25e70 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
25e80 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
25e90 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
25ea0 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
25eb0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
25ec0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
25ed0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
25ee0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
25ef0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25f00 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
25f10 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
25f20 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25f30 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
25f40 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
25f50 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
25f60 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
25f70 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
25f80 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
25f90 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
25fa0 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
25fb0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
25fc0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
25fd0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
25fe0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
25ff0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
26000 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
26010 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
26020 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
26030 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
26040 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
26050 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
26060 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
26070 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
26080 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
26090 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
260a0 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
260b0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
260c0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
260d0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
260e0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
260f0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
26100 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
26110 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
26120 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
26130 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
26140 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
26150 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
26160 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
26170 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
26180 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
26190 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
261a0 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
261b0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
261c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
261d0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
261e0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
261f0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
26200 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
26210 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
26220 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
26230 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
26240 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
26250 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
26260 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
26270 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
26280 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
26290 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
262a0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
262b0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
262c0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
262d0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
262e0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
262f0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
26300 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
26310 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
26320 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
26330 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
26340 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
26350 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
26360 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
26370 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
26380 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
26390 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
263a0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
263b0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
263c0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
263d0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
263e0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
263f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
26400 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
26410 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
26420 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
26430 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
26440 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
26450 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
26460 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
26470 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
26480 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
26490 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
264a0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
264b0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
264c0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
264d0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
264e0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
264f0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
26500 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26510 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
26520 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26530 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26540 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
26550 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
26560 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
26570 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
26580 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
26590 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
265a0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
265b0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
265c0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
265d0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
265e0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
265f0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26600 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
26610 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
26620 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
26630 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
26640 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
26650 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
26660 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
26670 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
26680 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
26690 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
266a0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
266b0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
266c0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
266d0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
266e0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
266f0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
26700 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
26710 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
26720 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
26730 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
26740 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
26750 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
26760 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
26770 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
26780 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
26790 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
267a0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
267b0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
267c0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
267d0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
267e0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
267f0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
26800 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
26810 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
26820 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
26830 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26840 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
26850 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
26860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
26870 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
26880 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
26890 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
268a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
268b0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
268c0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
268d0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
268e0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
268f0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
26900 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
26910 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
26920 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
26930 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
26940 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
26950 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
26960 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26970 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
26980 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26990 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
269a0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
269b0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
269c0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
269d0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
269e0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
269f0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26a00 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
26a10 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
26a20 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
26a30 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
26a40 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
26a50 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
26a60 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
26a70 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
26a80 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
26a90 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
26aa0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
26ab0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
26ac0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
26ad0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
26ae0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
26af0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
26b00 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
26b10 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
26b20 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
26b30 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
26b40 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
26b50 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
26b60 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
26b70 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
26b80 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
26b90 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
26ba0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
26bb0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
26bc0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
26bd0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
26be0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
26bf0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26c00 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
26c10 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
26c20 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
26c30 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
26c40 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26c50 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
26c60 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26c70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
26c80 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
26c90 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
26ca0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
26cb0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
26cc0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
26cd0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
26ce0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
26cf0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26d00 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
26d10 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
26d20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
26d30 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26d40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
26d50 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26d60 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
26d70 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
26d80 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
26d90 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
26da0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
26db0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
26dc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26dd0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
26de0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
26df0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
26e00 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
26e10 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
26e20 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
26e30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26e40 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
26e50 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
26e60 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
26e70 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  LL sqlite3_open(
26e80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
26e90 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26ea0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26eb0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26ec0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26ed0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26ee0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26ef0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26f00 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
26f10 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  L sqlite3_open16
26f20 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
26f30 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26f40 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26f50 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
26f60 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
26f70 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
26f80 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
26f90 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26fa0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
26fb0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
26fc0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
26fd0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
26fe0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
26ff0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
27000 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
27010 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
27020 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
27030 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
27040 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27050 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
27060 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
27070 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
27080 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
27090 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
270a0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
270b0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
270c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
270d0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
270e0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
270f0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
27100 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
27110 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
27120 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
27130 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
27140 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
27150 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
27160 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
27170 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
27180 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
27190 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
271a0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
271b0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
271c0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
271d0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
271e0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
271f0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
27200 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
27210 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
27220 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
27230 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
27240 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
27250 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
27260 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
27270 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
27280 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
27290 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
272a0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
272b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
272c0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
272d0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
272e0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
272f0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
27300 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
27310 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
27320 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
27330 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27340 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
27350 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
27360 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
27370 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
27380 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27390 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
273a0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
273b0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
273c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
273d0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
273e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
273f0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
27400 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
27410 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
27420 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
27430 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
27440 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
27450 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
27460 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
27470 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27480 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27490 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
274a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
274b0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
274c0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
274d0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
274e0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
274f0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27500 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27510 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27520 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
27530 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27540 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
27550 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
27560 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
27570 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27580 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
27590 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
275a0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
275b0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
275c0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
275d0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
275e0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
275f0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27600 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27610 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27620 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
27630 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
27640 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27650 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
27660 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
27670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27680 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
27690 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
276a0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
276b0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
276c0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
276d0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
276e0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
276f0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27700 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27710 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27720 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27730 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
27740 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
27750 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
27760 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
27770 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
27780 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
27790 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
277a0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
277b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
277c0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
277d0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
277e0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
277f0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27800 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27810 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27820 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27830 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
27840 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
27850 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27860 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
27870 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
27880 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
27890 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
278a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
278b0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
278c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
278d0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
278e0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
278f0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
27900 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
27910 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
27920 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
27930 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
27940 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
27950 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
27960 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
27970 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
27980 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
27990 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
279a0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
279b0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
279c0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
279d0 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
279e0 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
279f0 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
27a00 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
27a10 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
27a20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
27a30 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
27a40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
27a50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
27a60 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
27a70 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
27a80 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
27a90 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
27aa0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
27ab0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
27ac0 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
27ad0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
27ae0 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
27af0 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
27b00 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
27b10 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
27b20 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
27b30 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
27b40 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
27b50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
27b60 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
27b70 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
27b80 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
27b90 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
27ba0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
27bb0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
27bc0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27bd0 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
27be0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27bf0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
27c00 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
27c10 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
27c20 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
27c30 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
27c40 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
27c50 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
27c60 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
27c70 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
27c80 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
27c90 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
27ca0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
27cb0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
27cc0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
27cd0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
27ce0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
27cf0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
27d00 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
27d10 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
27d20 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
27d30 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
27d40 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
27d50 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
27d60 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
27d70 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
27d80 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
27d90 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
27da0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
27db0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
27dc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27dd0 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
27de0 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
27df0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27e00 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
27e10 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
27e20 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27e30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
27e40 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
27e50 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
27e60 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
27e70 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
27e80 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
27e90 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
27ea0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
27eb0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
27ec0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
27ed0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
27ee0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
27ef0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
27f00 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
27f10 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
27f20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
27f30 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
27f40 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
27f50 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
27f60 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
27f70 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
27f80 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
27f90 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
27fa0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
27fb0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
27fc0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
27fd0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
27fe0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
27ff0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
28000 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
28010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28020 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
28030 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
28040 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
28050 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
28060 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
28070 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
28080 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
28090 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
280a0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
280b0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
280c0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
280d0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
280e0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
280f0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
28100 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
28110 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
28120 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
28130 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
28140 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
28150 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
28160 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
28170 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
28180 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
28190 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
281a0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
281b0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
281c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
281d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63  ALL sqlite3_errc
281e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
281f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28200 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28210 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
28220 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28230 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
28240 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
28250 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
28260 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
28270 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
28280 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
28290 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
282a0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
282b0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
282c0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
282d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
282e0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
282f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28300 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
28310 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
28320 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
28330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
28340 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
28350 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
28360 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
28370 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
28380 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
28390 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
283a0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
283b0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
283c0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
283d0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
283e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
283f0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
28400 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
28410 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
28420 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
28430 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
28440 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
28450 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
28460 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
28470 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
28480 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
28490 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
284a0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
284b0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
284c0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
284d0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
284e0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
284f0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28500 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28510 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28520 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28530 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
28540 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28550 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
28570 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
28580 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
28590 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
285a0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
285b0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
285c0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
285d0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
285e0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
285f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28600 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28610 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28620 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28630 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28640 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28650 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
28660 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
28670 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
28680 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
28690 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
286a0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
286b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
286c0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
286d0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
286e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
286f0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28700 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28710 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28720 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28730 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
28740 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
28750 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
28760 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
28770 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
28780 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
28790 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
287a0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
287b0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
287c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
287d0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
287e0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
287f0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28800 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28810 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28820 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28830 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
28840 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
28850 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
28860 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
28870 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28880 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
28890 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
288a0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
288b0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
288c0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
288d0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
288e0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
288f0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28900 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28910 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28920 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
28930 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
28940 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
28950 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
28960 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
28970 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
28980 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
28990 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
289a0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
289b0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
289c0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
289d0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
289e0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
289f0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
28a00 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
28a10 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
28a20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
28a30 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
28a40 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
28a50 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
28a60 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
28a70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
28a80 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
28a90 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
28aa0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
28ab0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28ac0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
28ad0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
28ae0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
28af0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
28b00 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
28b10 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
28b20 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
28b30 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
28b40 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
28b50 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
28b60 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
28b70 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
28b80 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
28b90 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
28ba0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
28bb0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
28bc0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
28bd0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
28be0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
28bf0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
28c00 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
28c10 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
28c20 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
28c30 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
28c40 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
28c50 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
28c60 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
28c70 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
28c80 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
28c90 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
28ca0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
28cb0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
28cc0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
28cd0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
28ce0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28cf0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
28d00 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
28d10 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
28d20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
28d30 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
28d40 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
28d50 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
28d60 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
28d70 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
28d80 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
28d90 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
28da0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
28db0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
28dc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
28dd0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
28de0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
28df0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
28e00 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
28e10 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
28e20 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
28e30 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
28e40 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
28e50 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
28e60 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
28e70 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
28e80 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
28e90 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
28ea0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
28eb0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
28ec0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
28ed0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28ee0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28ef0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
28f00 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
28f10 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
28f20 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
28f30 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
28f40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
28f50 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
28f60 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
28f70 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
28f80 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
28f90 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
28fa0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
28fb0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
28fc0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
28fd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
28fe0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
28ff0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
29000 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
29010 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
29020 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
29030 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
29040 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
29050 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
29060 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
29070 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
29080 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29090 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
290a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
290b0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
290c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
290d0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
290e0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
290f0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
29100 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29110 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29120 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
29130 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29140 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
29150 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
29160 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
29170 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
29180 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
29190 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
291a0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
291b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
291c0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
291d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
291e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
291f0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
29200 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
29210 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
29220 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
29230 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29240 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
29250 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
29260 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
29270 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
29280 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29290 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
292a0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
292b0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
292c0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
292d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
292e0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
292f0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
29300 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
29310 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29320 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
29330 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
29340 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
29350 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
29360 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29370 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
29380 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
29390 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
293a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
293b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
293c0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
293d0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
293e0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
293f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29400 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
29410 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
29420 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
29430 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
29440 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
29450 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
29460 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
29470 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
29480 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
29490 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
294a0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
294b0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
294c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
294d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
294e0 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
294f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29500 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
29510 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29520 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
29530 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
29540 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
29550 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29560 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
29570 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
29580 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
29590 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
295a0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
295b0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
295c0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
295d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
295e0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
295f0 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
29600 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29610 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29620 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
29630 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
29640 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
29650 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
29660 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
29670 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
29680 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29690 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
296a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
296b0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
296c0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
296d0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
296e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
296f0 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
29700 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
29710 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29720 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
29730 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29740 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29750 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
29760 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
29770 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29780 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
29790 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
297a0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
297b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
297c0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
297d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
297e0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
297f0 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
29800 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29810 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
29820 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
29830 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
29840 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29850 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
29860 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
29870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
29880 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
29890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
298a0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
298b0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
298c0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
298d0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
298e0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
298f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29900 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
29910 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
29920 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29930 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
29940 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
29950 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
29960 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
29970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
29980 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
29990 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
299a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
299b0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
299c0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
299d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
299e0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
299f0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
29a00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29a10 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29a20 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
29a30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29a40 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
29a50 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
29a60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29a70 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
29a80 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
29a90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29aa0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29ab0 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
29ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
29ad0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
29ae0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
29af0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
29b00 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
29b10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29b20 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
29b30 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
29b40 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
29b50 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
29b60 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
29b70 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
29b80 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
29b90 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
29ba0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
29bb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
29bc0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
29bd0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
29be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
29bf0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
29c00 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
29c10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29c20 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
29c30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
29c40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
29c50 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
29c60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29c70 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
29c80 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
29c90 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
29ca0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
29cb0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
29cc0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
29cd0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
29ce0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
29cf0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
29d00 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
29d10 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29d20 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
29d30 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
29d40 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29d50 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
29d60 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
29d70 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
29d80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
29d90 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
29da0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29db0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
29dc0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
29dd0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29de0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
29df0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
29e00 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29e10 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
29e20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
29e30 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
29e40 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
29e50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
29e60 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
29e70 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
29e80 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
29e90 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
29ea0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
29eb0 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
29ec0 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
29ed0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
29ee0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
29ef0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
29f00 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
29f10 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
29f20 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
29f30 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
29f40 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
29f50 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
29f60 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
29f70 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
29f80 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
29f90 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
29fa0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
29fb0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
29fc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
29fd0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
29fe0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
29ff0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
2a000 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
2a010 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
2a020 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2a030 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
2a040 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
2a050 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
2a060 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2a070 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
2a080 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a090 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
2a0a0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
2a0b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a0c0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
2a0d0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
2a0e0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
2a0f0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
2a100 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
2a110 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
2a120 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
2a130 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
2a140 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
2a150 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
2a160 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
2a170 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
2a180 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
2a190 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
2a1a0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
2a1b0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2a1c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a1d0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
2a1e0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2a1f0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
2a200 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
2a210 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
2a220 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
2a230 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
2a240 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
2a250 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
2a260 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
2a270 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2a280 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a290 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2a2a0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
2a2b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a2c0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
2a2d0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
2a2e0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2a2f0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
2a300 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
2a310 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
2a320 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
2a330 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
2a340 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
2a350 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
2a360 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2a370 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
2a380 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2a390 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
2a3a0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2a3b0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
2a3c0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
2a3d0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
2a3e0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
2a3f0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
2a400 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
2a410 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
2a420 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
2a430 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
2a440 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
2a450 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
2a460 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
2a470 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
2a480 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2a490 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2a4a0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2a4b0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2a4c0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2a4d0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2a4e0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2a4f0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2a500 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2a510 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2a520 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2a530 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2a540 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2a550 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2a560 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2a570 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2a580 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2a590 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2a5a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2a5b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a5c0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2a5d0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2a5e0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2a5f0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2a600 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2a610 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2a620 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2a630 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a640 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2a650 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2a660 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2a670 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2a680 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2a690 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2a6a0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2a6b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2a6c0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2a6d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2a6e0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2a6f0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2a700 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2a710 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2a720 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2a730 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2a740 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2a750 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2a760 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a770 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2a780 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2a790 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2a7a0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2a7b0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2a7c0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2a7d0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2a7e0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a7f0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2a800 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2a810 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2a820 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2a830 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2a840 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2a850 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2a860 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2a870 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2a880 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2a890 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2a8a0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2a8b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2a8c0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2a8d0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2a8e0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2a8f0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2a900 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2a910 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2a920 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2a930 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2a940 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a950 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2a960 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2a970 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2a980 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2a990 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2a9a0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2a9b0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2a9c0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2a9d0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2a9e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2a9f0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2aa00 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
2aa10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2aa20 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2aa30 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
2aa40 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2aa50 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2aa60 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2aa70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2aa80 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2aa90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2aaa0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2aab0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2aac0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2aad0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2aae0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2aaf0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ab00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ab10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ab20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ab30 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2ab40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ab50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ab60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ab70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ab80 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ab90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2aba0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2abb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2abc0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2abd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2abe0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2abf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ac00 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2ac10 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ac20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2ac30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ac40 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2ac50 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ac60 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ac70 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ac80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ac90 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2aca0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2acb0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2acc0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2acd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ace0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2acf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ad00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ad10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ad20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ad30 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ad40 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ad50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ad60 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2ad70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ad80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2ad90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ada0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2adb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2adc0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2add0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ade0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2adf0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2ae00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ae10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ae20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ae30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ae40 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ae50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ae60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2ae70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2ae80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ae90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2aea0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2aeb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2aec0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2aed0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2aee0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2aef0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2af00 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2af10 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2af20 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2af30 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2af40 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2af50 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2af60 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2af70 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2af80 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2af90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2afa0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2afb0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2afc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2afd0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2afe0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2aff0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
2b000 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
2b010 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
2b020 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2b030 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
2b040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b050 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
2b060 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
2b070 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
2b080 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b090 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2b0a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b0b0 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
2b0c0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2b0d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b0e0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2b0f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b110 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2b120 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2b130 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2b140 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2b150 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2b160 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2b170 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2b180 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b190 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2b1a0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2b1b0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2b1c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2b1d0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2b1e0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2b1f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2b200 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2b210 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2b220 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b230 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b240 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2b250 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2b260 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2b270 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2b280 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2b290 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2b2a0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2b2b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2b2c0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2b2d0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2b2e0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2b2f0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2b300 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2b310 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2b320 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2b330 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2b340 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2b350 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2b360 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2b370 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2b380 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2b390 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2b3a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2b3b0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2b3c0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2b3d0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2b3e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2b3f0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2b400 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b410 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2b420 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2b430 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2b440 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2b450 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2b460 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2b470 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2b480 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2b490 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2b4a0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2b4b0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2b4c0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2b4d0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2b4e0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2b4f0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2b500 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2b510 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2b520 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2b530 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2b540 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2b550 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2b560 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2b570 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2b580 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2b590 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2b5a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b5b0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2b5c0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2b5d0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2b5e0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2b5f0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2b600 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2b610 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2b620 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2b630 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2b640 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2b650 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2b660 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   disk..*/.SQLITE
2b670 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b680 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b690 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
2b6a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b6b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b6c0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2b6d0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2b6e0 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
2b6f0 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
2b700 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b710 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b720 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
2b730 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b740 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2b750 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
2b760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b770 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
2b780 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
2b790 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2b7a0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
2b7b0 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20  has neither run 
2b7c0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72  to completion (r
2b7d0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2b7e0 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73  TE_DONE] from [s
2b7f0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29  qlite3_step(S)])
2b800 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73   nor.** been res
2b810 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
2b820 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
2b830 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b840 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
2b850 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
2b860 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
2b870 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
2b880 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
2b890 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
2b8a0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
2b8b0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
2b8c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2b8d0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
2b8e0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b8f0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2b900 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
2b910 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2b920 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2b930 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
2b940 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
2b950 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
2b960 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
2b970 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
2b980 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
2b990 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
2b9a0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
2b9b0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
2b9c0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
2b9d0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
2b9e0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
2b9f0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
2ba00 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
2ba10 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
2ba20 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
2ba30 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
2ba40 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
2ba50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ba60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2ba70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2ba80 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2ba90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2baa0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2bab0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2bac0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2bad0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2bae0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2baf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2bb00 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2bb10 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2bb20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bb30 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2bb40 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2bb50 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2bb60 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2bb70 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2bb80 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2bb90 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2bba0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2bbb0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2bbc0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bbd0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2bbe0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2bbf0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2bc00 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2bc10 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2bc20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2bc30 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2bc40 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2bc50 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2bc60 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2bc70 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2bc80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bc90 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2bca0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2bcb0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2bcc0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2bcd0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2bce0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2bcf0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2bd00 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2bd10 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2bd20 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2bd30 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2bd40 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2bd50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bd60 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2bd70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2bd80 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2bd90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2bda0 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2bdb0 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2bdc0 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2bdd0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2bde0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2bdf0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2be00 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2be10 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2be20 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2be30 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2be40 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2be50 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2be60 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2be70 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2be80 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2be90 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2bea0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2beb0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2bec0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2bed0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2bee0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2bef0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2bf00 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2bf10 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2bf20 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2bf30 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2bf40 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2bf50 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2bf60 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2bf70 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2bf80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2bf90 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2bfa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2bfb0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2bfc0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2bfd0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2bfe0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2bff0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2c000 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c010 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2c020 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2c030 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2c040 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2c050 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2c060 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2c070 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2c080 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2c090 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2c0a0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2c0b0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2c0c0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2c0d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c0e0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2c0f0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2c100 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2c110 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c120 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2c130 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2c140 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2c150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2c160 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c170 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c180 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2c190 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2c1a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2c1b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2c1c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2c1d0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2c1e0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2c1f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c200 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2c210 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2c220 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
2c230 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
2c240 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2c250 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
2c260 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c270 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2c280 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2c290 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2c2a0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2c2b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c2c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2c2d0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2c2e0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
2c2f0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2c300 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2c310 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2c320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2c330 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2c340 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2c350 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2c360 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2c370 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2c380 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2c390 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2c3a0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2c3b0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2c3c0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2c3d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c3e0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2c3f0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2c400 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c410 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2c420 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2c430 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2c440 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2c450 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2c460 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2c470 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2c480 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2c490 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2c4a0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2c4b0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2c4c0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2c4d0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2c4e0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2c4f0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2c500 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2c510 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2c520 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2c530 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2c540 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2c550 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2c560 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2c570 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2c580 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2c590 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2c5a0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2c5b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2c5c0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2c5d0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2c5e0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2c5f0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2c600 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2c610 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c620 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2c630 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2c640 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2c650 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c660 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2c670 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2c680 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2c690 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2c6a0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2c6b0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2c6c0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2c6d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2c6e0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2c6f0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2c700 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2c710 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2c720 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2c730 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2c740 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2c750 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2c760 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2c770 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2c780 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2c790 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2c7a0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2c7b0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2c7c0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2c7d0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2c7e0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2c7f0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2c800 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2c810 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2c820 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2c830 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2c840 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2c850 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2c860 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2c870 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2c880 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2c890 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2c8a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2c8b0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2c8c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2c8d0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2c8e0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2c8f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2c900 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2c910 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2c920 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2c930 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2c940 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2c950 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2c960 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2c970 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2c980 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2c990 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2c9a0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2c9b0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2c9c0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2c9d0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2c9e0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2c9f0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2ca00 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2ca10 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2ca20 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2ca30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ca40 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2ca50 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2ca60 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2ca70 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2ca80 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2ca90 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2caa0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2cab0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2cac0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2cad0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2cae0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2caf0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2cb00 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2cb10 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2cb20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2cb30 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2cb40 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2cb50 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2cb60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2cb70 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cb80 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2cb90 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2cba0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2cbb0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2cbc0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2cbd0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2cbe0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2cbf0 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2cc00 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2cc10 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2cc20 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2cc30 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2cc40 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2cc50 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2cc60 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2cc70 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2cc80 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2cc90 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2cca0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2ccb0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2ccc0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2ccd0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2cce0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2ccf0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2cd00 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2cd10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2cd20 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2cd30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2cd40 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2cd50 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2cd60 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2cd70 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2cd80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2cd90 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2cda0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2cdb0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2cdc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2cdd0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2cde0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2cdf0 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2ce00 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2ce10 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2ce20 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2ce30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2ce40 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2ce50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2ce60 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2ce70 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2ce80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2ce90 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2cea0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2ceb0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2cec0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2ced0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2cee0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2cef0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2cf00 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2cf10 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2cf20 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2cf30 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2cf40 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2cf50 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2cf60 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cf70 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2cf80 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2cf90 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2cfa0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2cfb0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2cfc0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2cfd0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2cfe0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2cff0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2d000 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2d010 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2d020 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2d030 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2d040 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2d050 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2d060 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2d070 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2d080 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2d090 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2d0a0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2d0b0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2d0c0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2d0d0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2d0e0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2d0f0 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2d100 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2d110 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2d120 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2d130 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2d140 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2d150 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2d160 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2d170 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2d180 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2d190 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2d1a0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2d1b0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2d1c0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2d1d0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2d1e0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2d1f0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2d200 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2d210 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2d220 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2d230 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2d240 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d250 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2d260 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2d270 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2d280 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d290 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2d2a0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2d2b0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2d2c0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2d2d0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2d2e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2d2f0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2d300 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2d310 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2d320 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2d330 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2d340 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2d350 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2d360 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2d370 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2d380 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2d390 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2d3a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2d3b0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2d3c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2d3d0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2d3e0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2d3f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2d400 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2d410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d420 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2d430 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2d440 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2d450 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2d460 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2d470 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2d480 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2d490 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2d4a0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2d4b0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2d4c0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2d4d0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2d4e0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2d4f0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2d500 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2d510 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2d520 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2d530 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2d540 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d550 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2d560 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2d570 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2d580 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2d590 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2d5a0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2d5b0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2d5c0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2d5d0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2d5e0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2d5f0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2d600 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2d610 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2d620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d630 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2d640 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2d650 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2d660 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2d670 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2d680 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2d690 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d6a0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2d6b0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2d6c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d6d0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2d6e0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2d6f0 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2d700 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d710 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2d720 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2d730 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2d740 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2d750 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2d760 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2d770 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2d780 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2d790 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2d7a0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2d7b0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2d7c0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2d7d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d7e0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2d7f0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2d800 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2d810 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2d820 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2d830 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2d840 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2d850 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2d860 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2d870 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2d880 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2d890 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2d8a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2d8b0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2d8c0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2d8d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2d8e0 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2d8f0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2d900 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2d910 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2d920 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2d930 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2d940 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2d950 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2d960 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2d970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2d980 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2d990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2d9a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2d9b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2d9c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d9d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2d9e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2d9f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2da00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2da10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2da20 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2da30 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2da40 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2da50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2da60 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2da70 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2da80 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2da90 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2daa0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2dab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dac0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2dad0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2dae0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2daf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2db00 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2db10 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2db20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2db30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2db40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2db50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2db60 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
2db70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2db80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2db90 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2dba0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2dbb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2dbc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2dbd0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2dbe0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2dbf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2dc00 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2dc10 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2dc20 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2dc30 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2dc40 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2dc50 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2dc60 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2dc70 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2dc80 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2dc90 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2dca0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2dcb0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2dcc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2dcd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2dce0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2dcf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2dd00 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2dd10 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2dd20 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2dd30 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2dd40 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2dd50 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2dd60 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2dd70 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ing);.SQLITE_API
2dd80 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2dd90 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2dda0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2ddb0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2ddc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2ddd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dde0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2ddf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2de00 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2de10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2de20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2de30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2de40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2de50 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2de60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2de70 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2de80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2de90 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2dea0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2deb0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2dec0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2ded0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2dee0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2def0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2df00 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2df10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2df20 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2df30 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2df40 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2df50 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2df60 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2df70 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2df80 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2df90 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2dfa0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2dfb0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2dfc0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2dfd0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2dfe0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2dff0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2e000 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2e010 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2e020 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2e030 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2e040 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2e050 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2e060 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2e070 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2e080 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2e090 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2e0a0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2e0b0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2e0c0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2e0d0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2e0e0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2e0f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e100 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e110 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e130 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2e140 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2e150 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e160 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2e170 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e180 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e190 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e1a0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2e1b0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e1c0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2e1d0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2e1e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e1f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2e200 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2e210 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2e220 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2e230 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2e240 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2e250 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2e260 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e270 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2e280 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2e290 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2e2a0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2e2b0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2e2c0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2e2d0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2e2e0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2e2f0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2e300 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2e310 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2e320 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2e330 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2e340 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2e350 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2e360 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2e370 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2e380 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2e390 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2e3a0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2e3b0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2e3c0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2e3d0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2e3e0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2e3f0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2e400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2e410 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2e420 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2e430 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2e440 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2e450 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2e460 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2e470 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2e480 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2e490 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2e4a0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2e4b0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2e4c0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2e4d0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2e4e0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2e4f0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2e500 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2e510 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2e520 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2e530 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e540 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2e550 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e560 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e570 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e580 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e590 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e5a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2e5b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e5c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e5d0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2e5e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2e5f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2e600 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e610 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2e620 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2e630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2e640 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2e650 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2e660 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2e670 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e680 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2e690 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2e6a0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2e6b0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2e6c0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2e6d0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2e6e0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2e6f0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2e700 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2e710 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e720 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2e730 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2e740 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2e750 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2e760 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2e770 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2e780 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2e790 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2e7a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2e7b0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2e7c0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2e7d0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2e7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e7f0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2e800 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e810 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e820 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e830 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e840 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2e850 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e860 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e870 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  ame()]..*/.SQLIT
2e880 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e890 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e8a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e8b0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2e8c0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2e8d0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2e8e0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2e8f0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2e900 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2e910 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2e920 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e930 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2e940 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2e950 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2e960 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2e970 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2e980 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e990 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2e9a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e9b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2e9c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2e9d0 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2e9e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2e9f0 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2ea00 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2ea10 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65  CALL sqlite3_cle
2ea20 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2ea30 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2ea40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2ea50 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2ea60 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2ea70 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2ea80 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2ea90 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2eaa0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2eab0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2eac0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2ead0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eae0 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2eaf0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2eb00 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2eb10 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2eb20 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2eb30 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2eb40 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2eb50 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2eb60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2eb70 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2eb80 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2eb90 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2eba0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2ebb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ebc0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2ebd0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2ebe0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2ebf0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2ec00 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ec10 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2ec20 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2ec30 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2ec40 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2ec50 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2ec60 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2ec70 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2ec80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2ec90 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2eca0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ecb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2ecc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2ecd0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2ece0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2ecf0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2ed00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ed10 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2ed20 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2ed30 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2ed40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ed50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ed60 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2ed70 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2ed80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2ed90 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2eda0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2edb0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2edc0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2edd0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2ede0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2edf0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2ee00 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2ee10 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2ee20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ee30 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2ee40 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2ee50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2ee60 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2ee70 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2ee80 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2ee90 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2eea0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2eeb0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2eec0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2eed0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2eee0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2eef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ef00 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2ef10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2ef20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2ef30 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2ef40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2ef50 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2ef60 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2ef70 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2ef80 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2ef90 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2efa0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2efb0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2efc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2efd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2efe0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2eff0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2f000 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f010 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2f020 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2f030 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2f040 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2f050 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2f060 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2f070 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2f080 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2f090 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2f0a0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2f0b0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2f0c0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2f0d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f0e0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2f0f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2f100 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2f110 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2f120 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f130 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2f140 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f150 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2f160 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f170 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2f180 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2f190 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2f1a0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2f1b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f1c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2f1d0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2f1e0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2f1f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2f200 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2f210 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2f220 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2f230 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2f240 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2f250 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2f260 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2f270 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2f280 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2f290 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2f2a0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2f2b0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2f2c0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2f2d0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2f2e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2f2f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2f300 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2f310 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2f320 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2f330 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2f340 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2f350 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2f360 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2f370 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2f380 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2f390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f3a0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2f3b0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2f3c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2f3d0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2f3e0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2f3f0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2f400 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2f410 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2f420 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2f430 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2f440 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2f450 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2f460 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2f470 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2f480 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2f490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2f4a0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2f4b0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2f4c0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2f4d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2f4e0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2f4f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2f500 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2f510 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2f520 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2f530 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2f540 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2f550 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2f560 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2f570 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2f580 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2f590 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2f5a0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2f5b0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2f5c0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2f5d0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2f5e0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2f5f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2f600 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2f610 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2f620 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2f630 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2f640 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2f650 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2f660 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2f670 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2f680 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2f690 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2f6a0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2f6b0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2f6c0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2f6d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2f6e0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2f6f0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2f700 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f710 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2f720 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2f730 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2f740 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2f750 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2f760 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2f770 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2f780 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2f790 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2f7a0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2f7b0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2f7c0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2f7d0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2f7e0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2f7f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2f800 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2f810 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f820 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f830 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f840 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f850 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f860 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f870 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2f880 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f890 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f8a0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2f8b0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2f8c0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2f8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2f8e0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2f8f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2f900 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2f910 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f920 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2f930 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2f940 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2f950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f960 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2f970 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2f980 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2f990 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2f9a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2f9b0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2f9c0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2f9d0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2f9e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f9f0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2fa00 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2fa10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2fa20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2fa30 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2fa40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2fa50 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2fa60 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2fa70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2fa80 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2fa90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2faa0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2fab0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2fac0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2fad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2fae0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2faf0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2fb00 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2fb10 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2fb20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb30 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2fb40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2fb50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fb60 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2fb70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2fb80 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2fb90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2fba0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2fbb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
2fbc0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2fbd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2fbe0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2fbf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2fc00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2fc10 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2fc20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2fc30 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2fc40 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2fc50 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2fc60 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2fc70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2fc80 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2fc90 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2fca0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2fcb0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2fcc0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2fcd0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2fce0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2fcf0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2fd00 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2fd10 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2fd20 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2fd30 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2fd40 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2fd50 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2fd60 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2fd70 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2fd80 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2fd90 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2fda0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2fdb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2fdc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2fdd0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2fde0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2fdf0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2fe00 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2fe10 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2fe20 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2fe30 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2fe40 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2fe50 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2fe60 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2fe70 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2fe80 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2fe90 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2fea0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2feb0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2fec0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2fed0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2fee0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2fef0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2ff00 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2ff10 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2ff20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2ff30 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2ff40 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2ff50 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2ff60 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2ff70 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2ff80 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2ff90 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2ffa0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2ffb0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2ffc0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2ffd0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2ffe0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2fff0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
30000 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
30010 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
30020 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
30030 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
30040 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
30050 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
30060 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
30070 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
30080 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
30090 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
300a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
300b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
300c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
300d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
300e0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
300f0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
30100 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
30110 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
30120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
30130 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
30140 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
30150 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
30160 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
30170 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
30180 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30190 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
301a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
301b0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
301c0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
301d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
301e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
301f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30200 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
30210 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
30220 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
30230 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
30240 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30250 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
30260 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
30270 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
30280 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
30290 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
302a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
302b0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
302c0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
302d0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
302e0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
302f0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
30300 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
30310 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
30320 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
30330 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
30340 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
30350 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
30360 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
30370 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
30380 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
30390 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
303a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
303b0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
303c0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
303d0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
303e0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
303f0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
30400 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
30410 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30420 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
30430 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
30440 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
30450 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
30460 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
30470 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
30480 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
30490 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
304a0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
304b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
304c0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
304d0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
304e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
304f0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
30500 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
30510 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
30520 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
30530 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
30540 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
30550 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
30560 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
30570 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
30580 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
30590 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
305a0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
305b0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
305c0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
305d0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
305e0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
305f0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
30600 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30610 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
30620 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
30630 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
30640 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
30650 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
30660 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
30670 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
30680 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
30690 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
306a0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
306b0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
306c0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
306d0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
306e0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
306f0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
30700 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
30710 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
30720 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
30730 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
30740 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
30750 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
30760 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
30770 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
30780 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
30790 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
307a0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
307b0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
307c0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
307d0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
307e0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
307f0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
30800 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
30810 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
30820 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
30830 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
30840 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
30850 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
30860 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
30870 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
30880 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
30890 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
308a0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
308b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
308c0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
308d0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
308e0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
308f0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
30900 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
30910 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
30920 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
30930 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
30940 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
30950 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
30960 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
30970 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
30980 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
30990 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
309a0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
309b0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
309c0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
309d0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
309e0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
309f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
30a00 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
30a10 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
30a20 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
30a30 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
30a40 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
30a50 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
30a60 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
30a70 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
30a80 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
30a90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30aa0 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
30ab0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30ac0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
30ad0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
30ae0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
30af0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
30b00 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
30b10 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30b20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30b30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
30b40 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
30b50 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
30b60 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
30b70 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
30b80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
30b90 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
30ba0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
30bb0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
30bc0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
30bd0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
30be0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
30bf0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
30c00 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
30c10 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
30c20 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
30c30 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30c40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
30c50 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
30c60 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
30c70 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
30c80 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
30c90 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
30ca0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
30cb0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
30cc0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
30cd0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
30ce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30cf0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
30d00 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
30d10 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
30d20 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
30d30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
30d40 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
30d50 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
30d60 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
30d70 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
30d80 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
30d90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
30da0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
30db0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
30dc0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
30dd0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
30de0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
30df0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
30e00 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
30e10 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
30e20 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
30e30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
30e40 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
30e50 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
30e60 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
30e70 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
30e80 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
30e90 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
30ea0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
30eb0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
30ec0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
30ed0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
30ee0 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
30ef0 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
30f00 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
30f10 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
30f20 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
30f30 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
30f40 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
30f50 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
30f60 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
30f70 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
30f80 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
30f90 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
30fa0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
30fb0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
30fc0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
30fd0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
30fe0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
30ff0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
31000 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
31010 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
31020 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
31030 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
31040 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
31050 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
31060 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
31070 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
31080 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31090 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
310a0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
310b0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
310c0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
310d0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
310e0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
310f0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
31100 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
31110 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
31120 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
31130 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
31140 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
31150 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
31160 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
31170 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
31180 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
31190 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
311a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
311b0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
311c0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
311d0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
311e0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
311f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
31200 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
31210 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
31220 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
31230 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
31240 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
31250 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
31260 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
31270 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
31280 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
31290 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
312a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
312b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
312c0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
312d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
312e0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
312f0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
31300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31310 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31320 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31330 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
31340 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
31350 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
31360 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
31370 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
31380 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
31390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
313a0 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
313b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
313c0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
313d0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
313e0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
313f0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
31400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
31410 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
31420 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
31430 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
31440 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31450 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
31460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31470 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
31480 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
31490 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
314a0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
314b0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
314c0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
314d0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
314e0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
314f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31500 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
31510 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
31520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31530 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
31540 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
31550 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
31560 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31570 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
31580 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
31590 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
315a0 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
315b0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
315c0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
315d0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
315e0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
315f0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
31600 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
31610 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
31620 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
31630 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31640 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
31650 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
31660 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
31670 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
31680 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
31690 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
316a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
316b0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
316c0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
316d0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
316e0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
316f0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
31700 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
31710 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
31720 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
31730 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
31740 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31750 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
31760 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
31770 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
31780 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
31790 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
317a0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
317b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
317c0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
317d0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
317e0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
317f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
31800 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
31810 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
31820 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
31830 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
31840 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
31850 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
31860 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
31870 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
31880 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31890 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
318a0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
318b0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
318c0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
318d0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
318e0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
318f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31900 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
31910 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
31920 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
31930 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
31940 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
31950 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
31960 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
31970 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
31980 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
31990 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
319a0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
319b0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
319c0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
319d0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
319e0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
319f0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
31a00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31a10 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
31a20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31a30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
31a40 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
31a50 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
31a60 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
31a70 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
31a80 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
31a90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
31aa0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
31ab0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
31ac0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31ad0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
31ae0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
31af0 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
31b00 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
31b10 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
31b20 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
31b30 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
31b40 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
31b50 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
31b60 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
31b70 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
31b80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
31b90 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
31ba0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
31bb0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
31bc0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
31bd0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
31be0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
31bf0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
31c00 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
31c10 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
31c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31c30 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
31c40 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
31c50 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
31c60 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
31c70 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
31c80 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
31c90 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
31ca0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
31cb0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
31cc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31cd0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
31ce0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
31cf0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31d00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31d10 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
31d20 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
31d30 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
31d40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31d50 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
31d60 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
31d70 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
31d80 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
31d90 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
31da0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
31db0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
31dc0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
31dd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31de0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
31df0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
31e00 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
31e10 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
31e20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
31e30 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
31e40 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
31e50 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31e60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
31e70 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
31e80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
31e90 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
31ea0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
31eb0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
31ec0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31ed0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
31ee0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
31ef0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
31f00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
31f20 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
31f30 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
31f40 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
31f50 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
31f60 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
31f70 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
31f80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
31f90 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
31fa0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
31fb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
31fc0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
31fd0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
31fe0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
31ff0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
32000 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
32010 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
32030 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
32040 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
32050 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
32060 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
32070 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
32080 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
32090 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
320a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
320b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
320c0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
320d0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
320e0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
320f0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
32100 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32110 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32120 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
32130 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
32140 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
32150 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
32160 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
32170 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
32180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32190 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
321a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
321b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
321c0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
321d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
321e0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
321f0 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
32200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32210 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
32220 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
32230 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
32240 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32250 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
32260 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32270 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
32280 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
32290 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
322a0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
322b0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
322c0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
322d0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
322e0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
322f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
32300 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
32310 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
32320 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
32330 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32340 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
32350 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
32360 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32370 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
32380 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
32390 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
323a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
323b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
323c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
323d0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
323e0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
323f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32400 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
32410 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
32420 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
32430 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
32440 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
32450 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
32460 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32470 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
32480 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
32490 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
324a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
324b0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
324c0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
324d0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
324e0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
324f0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
32500 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32510 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32520 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32530 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32540 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
32550 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
32560 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
32570 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
32580 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
32590 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
325a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
325b0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
325c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
325d0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
325e0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
325f0 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
32600 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
32610 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
32620 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
32630 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
32640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32650 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
32660 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
32670 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
32680 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
32690 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
326a0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
326b0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
326c0 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
326d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
326e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
326f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32700 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
32710 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
32720 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
32730 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
32740 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
32750 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
32760 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
32770 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
32780 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
32790 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
327a0 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
327b0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
327c0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
327d0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
327e0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
327f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32800 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
32810 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
32820 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
32830 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
32840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
32850 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
32860 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
32870 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
32880 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
32890 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
328a0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
328b0 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
328c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
328d0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
328e0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
328f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
32900 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
32910 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
32920 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
32930 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
32940 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
32950 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
32960 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
32970 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
32980 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
32990 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
329a0 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
329b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
329c0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
329d0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
329e0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
329f0 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
32a00 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
32a10 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
32a20 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
32a30 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
32a40 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
32a50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
32a60 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
32a70 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
32a80 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
32a90 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
32aa0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
32ab0 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
32ac0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
32ad0 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
32ae0 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
32af0 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
32b00 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
32b10 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
32b20 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
32b30 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
32b40 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
32b50 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
32b60 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
32b70 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
32b80 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
32b90 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32ba0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32bb0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
32bc0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
32bd0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
32be0 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
32bf0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
32c00 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
32c10 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
32c20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
32c30 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
32c40 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
32c50 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
32c60 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
32c70 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
32c80 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
32c90 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
32ca0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32cb0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
32cc0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
32cd0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
32ce0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
32cf0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
32d00 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
32d10 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
32d20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
32d30 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
32d40 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
32d50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
32d60 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
32d70 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
32d80 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
32d90 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
32da0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
32db0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
32dc0 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
32dd0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32de0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
32df0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32e00 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
32e10 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32e20 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
32e30 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
32e40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
32e50 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
32e60 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
32e70 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
32e80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
32e90 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
32ea0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
32eb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
32ec0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
32ed0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32ee0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
32ef0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
32f00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
32f10 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
32f20 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
32f30 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
32f40 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
32f50 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
32f60 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
32f70 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
32f80 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
32f90 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
32fa0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
32fb0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
32fc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
32fd0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
32fe0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32ff0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
33000 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
33010 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
33020 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
33030 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
33040 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
33050 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
33060 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
33070 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
33080 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
33090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
330a0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
330b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
330c0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
330d0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
330e0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
330f0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
33100 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
33110 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
33120 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
33130 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
33140 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
33150 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33160 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
33170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33180 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
33190 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
331a0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
331b0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
331c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
331d0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
331e0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
331f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
33200 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
33210 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
33220 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
33230 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
33240 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
33250 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
33260 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
33270 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
33280 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
33290 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
332a0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
332b0 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
332c0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
332d0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
332e0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
332f0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
33300 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
33310 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
33320 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
33330 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
33340 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
33350 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
33360 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
33370 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
33380 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
33390 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
333a0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
333b0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
333c0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
333d0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
333e0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
333f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
33400 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
33410 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
33420 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
33430 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
33440 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
33450 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
33460 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
33470 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
33480 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33490 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
334a0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
334b0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
334c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
334d0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
334e0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
334f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
33500 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33510 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33520 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
33530 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
33540 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
33550 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
33560 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
33570 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33580 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
33590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
335a0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
335b0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
335c0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
335d0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
335e0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
335f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
33600 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33610 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
33620 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
33630 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
33640 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
33650 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
33660 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
33670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
33680 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
33690 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
336a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
336b0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
336c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
336d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
336e0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
336f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33700 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
33710 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
33720 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
33730 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
33740 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
33750 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
33760 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
33770 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
33780 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33790 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
337a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
337b0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
337c0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
337d0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
337e0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
337f0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
33800 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
33810 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
33820 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33830 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
33840 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33850 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
33860 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
33870 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
33880 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
33890 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
338a0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
338b0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
338c0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
338d0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
338e0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
338f0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
33900 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
33910 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
33920 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
33930 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
33940 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
33950 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
33960 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
33970 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
33980 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
33990 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
339a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
339b0 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
339c0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
339d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
339e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
339f0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
33a00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
33a10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
33a20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33a30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
33a40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33a50 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33a60 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
33a70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33a80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
33a90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33aa0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33ab0 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45  PI double SQLITE
33ac0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33ad0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
33ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33af0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33b00 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
33b10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33b20 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
33b30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33b40 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
33b50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
33b60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33b70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
33b80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33b90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33ba0 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
33bb0 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54  gned char *SQLIT
33bc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33bd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
33be0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33bf0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33c00 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
33c10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33c20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33c30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
33c40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33c50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
33c60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33c70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
33c80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
33c90 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33ca0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
33cb0 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ue *SQLITE_STDCA
33cc0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33cd0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
33ce0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33cf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d00 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
33d10 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
33d20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
33d30 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
33d40 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
33d50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33d60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
33d70 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
33d80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33d90 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
33da0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
33db0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
33dc0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
33dd0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
33de0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
33df0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
33e00 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
33e10 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
33e20 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
33e30 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
33e40 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33e50 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
33e60 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
33e70 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
33e80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
33e90 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
33ea0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
33eb0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
33ec0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
33ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33ee0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33ef0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
33f00 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
33f10 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
33f20 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
33f30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33f40 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
33f50 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
33f60 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
33f70 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
33f80 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
33f90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33fa0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
33fb0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
33fc0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
33fd0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
33fe0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
33ff0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
34000 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
34010 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
34020 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
34030 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
34040 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
34050 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
34060 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
34070 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
34080 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
34090 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
340a0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
340b0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
340c0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
340d0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
340e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
340f0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
34100 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34110 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
34120 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
34130 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
34140 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
34150 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
34160 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
34170 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
34180 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
34190 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
341a0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
341b0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
341c0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
341d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
341e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
341f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
34200 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
34210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34220 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
34230 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
34240 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
34250 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
34260 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
34270 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
34280 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
34290 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
342a0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
342b0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
342c0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
342d0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
342e0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
342f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
34300 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
34310 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
34320 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
34330 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
34340 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
34350 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
34360 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
34370 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
34380 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
34390 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
343a0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
343b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
343c0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
343d0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
343e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
343f0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
34400 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
34410 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
34420 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
34430 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
34440 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
34450 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
34460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34470 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
34480 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
34490 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
344a0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
344b0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
344c0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
344d0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
344e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
344f0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
34500 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
34510 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34520 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
34530 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
34540 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
34550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34560 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
34570 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
34580 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
34590 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
345a0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
345b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
345c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
345d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
345e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
345f0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
34600 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
34610 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
34620 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
34630 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
34640 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34650 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34660 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
34670 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
34680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34690 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
346a0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
346b0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
346c0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
346d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
346e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
346f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34700 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
34710 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34720 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34730 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
34740 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34750 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
34760 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
34770 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
34780 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
34790 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
347a0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
347b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
347c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
347d0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
347e0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
347f0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
34800 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
34810 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
34820 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
34830 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
34840 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
34850 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
34860 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
34870 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
34880 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
34890 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
348a0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
348b0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
348c0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
348d0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
348e0 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
348f0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34900 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
34910 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34920 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
34930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
34940 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
34950 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
34960 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
34970 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
34980 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
34990 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
349a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
349b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
349c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
349d0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
349e0 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
349f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
34a00 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34a10 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
34a20 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
34a30 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
34a40 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
34a50 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
34a60 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
34a70 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
34a80 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
34a90 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
34aa0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
34ab0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
34ac0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
34ad0 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
34ae0 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
34af0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
34b00 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
34b10 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
34b20 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
34b30 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
34b40 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
34b50 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
34b60 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
34b70 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
34b80 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
34b90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
34ba0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
34bb0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
34bc0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
34bd0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
34be0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34bf0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
34c00 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
34c10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
34c20 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
34c30 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
34c40 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
34c50 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
34c60 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
34c70 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
34c80 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
34c90 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
34ca0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
34cb0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
34cc0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
34cd0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
34ce0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
34cf0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
34d00 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
34d10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34d20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
34d30 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
34d40 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
34d50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
34d60 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
34d70 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
34d80 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
34d90 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
34da0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
34db0 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
34dc0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
34dd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
34de0 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
34df0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34e00 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
34e10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34e20 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
34e30 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
34e40 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
34e50 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
34e60 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
34e70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34e80 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
34e90 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
34ea0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
34eb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34ec0 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
34ed0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
34ee0 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
34ef0 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
34f00 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
34f10 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
34f20 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
34f30 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
34f40 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
34f50 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
34f60 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
34f70 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
34f80 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
34f90 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
34fa0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
34fb0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
34fc0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
34fd0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
34fe0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
34ff0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
35000 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
35010 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
35020 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
35030 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
35040 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
35050 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
35060 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
35070 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
35080 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
35090 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
350a0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
350b0 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
350c0 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
350d0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
350e0 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
350f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
35100 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
35110 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
35120 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
35130 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
35140 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
35150 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
35160 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
35170 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
35180 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
35190 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
351a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
351b0 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
351c0 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
351d0 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
351e0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
351f0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
35200 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
35210 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
35220 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
35230 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
35240 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
35250 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
35260 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
35270 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
35280 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
35290 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
352a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
352b0 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
352c0 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
352d0 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
352e0 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
352f0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
35300 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
35310 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
35320 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
35330 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
35340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
35350 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
35360 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
35370 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
35380 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
35390 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
353a0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
353b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
353c0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
353d0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
353e0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
353f0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
35400 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
35410 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
35420 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
35430 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
35440 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
35450 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
35460 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
35470 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
35480 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
35490 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
354a0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
354b0 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
354c0 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
354d0 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
354e0 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
354f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35500 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35510 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
35520 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
35530 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
35540 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
35550 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
35560 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
35570 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
35580 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
35590 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
355a0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
355b0 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
355c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
355d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
355e0 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
355f0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
35600 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
35610 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
35620 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35630 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
35640 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
35650 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
35660 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
35670 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
35680 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
35690 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
356a0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
356b0 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
356c0 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
356d0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
356e0 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
356f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35700 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35710 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
35720 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
35730 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
35740 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35750 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
35760 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
35770 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
35780 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
35790 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
357a0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
357b0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
357c0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
357d0 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
357e0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
357f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35800 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
35810 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
35820 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
35830 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
35840 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
35850 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35860 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
35870 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
35880 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
35890 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
358a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
358b0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
358c0 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
358d0 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
358e0 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
358f0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35900 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
35910 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
35920 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
35930 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
35940 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35950 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
35960 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
35970 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
35980 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
35990 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
359a0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
359b0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
359c0 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
359d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
359e0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
359f0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
35a00 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
35a10 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
35a20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
35a30 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
35a40 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
35a50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35a60 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
35a70 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
35a80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35a90 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
35aa0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
35ab0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
35ac0 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
35ad0 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
35ae0 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
35af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35b00 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
35b10 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
35b20 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
35b30 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
35b40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35b50 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
35b60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
35b70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65  CALL sqlite3_cre
35b80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
35b90 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
35ba0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
35bb0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
35bc0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
35bd0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
35be0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
35bf0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35c00 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35c10 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35c20 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35c30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35c50 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
35c60 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
35c70 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
35c80 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
35c90 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
35ca0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35cb0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
35cc0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
35cd0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
35ce0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
35cf0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
35d00 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
35d10 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
35d20 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35d30 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35d40 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
35d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35d60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35d70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
35d80 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
35d90 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
35da0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
35db0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35dc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35dd0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
35de0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
35df0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
35e00 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
35e10 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
35e20 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
35e30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
35e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35e60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
35e70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35e80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35e90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35ea0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
35eb0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
35ec0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
35ed0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
35ee0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
35ef0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
35f00 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
35f10 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
35f20 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
35f30 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
35f40 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
35f50 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
35f60 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
35f70 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
35f80 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
35f90 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
35fa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35fb0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
35fc0 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
35fd0 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
35fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
35ff0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
36000 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
36010 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
36020 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
36030 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
36040 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
36050 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
36060 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
36070 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
36080 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
36090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
360a0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
360b0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
360c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
360d0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
360e0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
360f0 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
36100 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
36110 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
36120 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
36130 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
36140 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
36150 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
36160 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
36170 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36180 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
36190 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
361a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
361b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
361c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
361d0 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
361e0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
361f0 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
36200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
36210 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
36220 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
36230 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
36240 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
36250 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
36260 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
36270 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
36280 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
36290 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
362a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
362b0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
362c0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
362d0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
362e0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
362f0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
36300 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
36310 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
36320 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
36330 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
36340 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
36350 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
36360 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
36370 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
36380 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
36390 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
363a0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
363b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
363c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
363d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
363e0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
363f0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36400 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
36410 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
36420 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
36430 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
36440 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36450 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
36460 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
36470 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
36480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36490 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
364a0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
364b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
364c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
364d0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
364e0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
364f0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36500 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
36510 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36520 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
36530 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
36540 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
36550 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
36560 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36570 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
36580 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
36590 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
365a0 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
365b0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
365c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
365d0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
365e0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
365f0 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
36600 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36610 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
36620 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
36630 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
36640 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
36650 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
36660 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
36670 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
36680 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
36690 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
366a0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
366b0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
366c0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
366d0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
366e0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
366f0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
36700 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
36710 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36720 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36730 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
36740 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36750 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
36760 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
36770 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
36780 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
36790 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
367a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
367b0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
367c0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
367d0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
367e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
367f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36800 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
36810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36820 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
36830 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36840 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
36850 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
36860 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
36870 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
36880 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
36890 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
368a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
368b0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
368c0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
368d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
368e0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
368f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
36900 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
36910 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
36920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
36930 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
36940 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
36950 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
36960 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
36970 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
36980 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
36990 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
369a0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
369b0 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
369c0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
369d0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
369e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
369f0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
36a00 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
36a10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
36a20 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
36a30 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
36a40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
36a50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36a60 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
36a70 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
36a80 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
36a90 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
36aa0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
36ab0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
36ac0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
36ad0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
36ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36af0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
36b00 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
36b10 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
36b20 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
36b30 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
36b40 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
36b50 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
36b60 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
36b70 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
36b80 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
36b90 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
36ba0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
36bb0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
36bc0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
36bd0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
36be0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
36bf0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
36c00 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
36c10 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
36c20 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
36c30 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
36c40 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
36c50 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
36c60 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
36c70 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
36c80 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
36c90 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
36ca0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
36cb0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
36cc0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
36cd0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
36ce0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
36cf0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
36d00 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
36d10 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
36d20 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
36d30 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
36d40 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
36d50 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
36d60 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
36d70 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
36d80 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
36d90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36da0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
36db0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36dc0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
36dd0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
36de0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
36df0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36e00 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
36e10 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
36e20 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
36e30 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
36e40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
36e50 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
36e60 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
36e70 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
36e80 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
36e90 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
36ea0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
36eb0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
36ec0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
36ed0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
36ee0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
36ef0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
36f00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36f10 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
36f20 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36f30 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
36f40 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36f50 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
36f60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
36f70 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
36f80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36f90 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
36fa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36fb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
36fc0 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
36fd0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
36fe0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36ff0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37000 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
37010 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
37020 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
37030 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
37040 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
37050 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
37060 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
37070 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
37080 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37090 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
370a0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
370b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
370c0 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
370d0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
370e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
370f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
37100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37110 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
37120 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
37130 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
37140 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37150 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37160 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
37170 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
37180 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
37190 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
371a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
371b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
371c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
371d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
371e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
371f0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
37200 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
37210 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
37220 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
37230 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
37240 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37260 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
37270 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
37280 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37290 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
372a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
372b0 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
372c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
372d0 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
372e0 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
372f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37300 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
37310 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
37320 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
37330 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
37340 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
37350 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
37360 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
37370 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
37380 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
37390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
373a0 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
373b0 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
373c0 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
373d0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
373e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
373f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
37400 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
37410 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
37420 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
37430 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
37440 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
37450 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
37460 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
37470 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
37480 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
37490 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  her..*/.SQLITE_A
374a0 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  PI unsigned int 
374b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
374c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
374d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
374e0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
374f0 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
37500 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
37510 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37520 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
37530 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
37540 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
37550 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
37560 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37570 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
37580 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
37590 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
375a0 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
375b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
375c0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
375d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
375e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
375f0 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
37600 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
37610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
37620 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
37630 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
37640 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
37650 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
37660 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
37670 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37680 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
37690 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
376a0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
376b0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
376c0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
376d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
376e0 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
376f0 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
37700 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
37710 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37720 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
37730 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
37740 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
37750 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  lue *SQLITE_STDC
37760 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37770 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
37780 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
37790 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
377a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
377b0 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
377c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
377d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
377e0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
377f0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
37800 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
37810 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37820 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
37830 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
37840 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
37850 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
37860 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
37870 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
37880 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
37890 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
378a0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
378b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
378c0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
378d0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
378e0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
378f0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37900 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
37910 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
37920 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
37930 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
37940 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37950 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
37960 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
37970 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
37980 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
37990 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
379a0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
379b0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
379c0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
379d0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
379e0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
379f0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
37a00 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37a10 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
37a20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
37a30 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
37a40 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
37a50 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
37a60 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
37a70 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
37a80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37a90 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
37aa0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
37ab0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
37ac0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
37ad0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
37ae0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
37af0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37b00 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
37b10 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
37b20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
37b30 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
37b40 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
37b50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37b60 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
37b70 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
37b80 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
37b90 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
37ba0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
37bb0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37bc0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
37bd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
37be0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
37bf0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
37c00 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
37c10 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
37c20 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
37c30 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37c40 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
37c50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
37c60 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
37c70 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
37c80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37c90 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
37ca0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
37cb0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
37cc0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
37cd0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
37ce0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
37cf0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
37d00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
37d10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37d20 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
37d30 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
37d40 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
37d50 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
37d60 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
37d70 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
37d80 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
37d90 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
37da0 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
37db0 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
37dc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
37dd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37de0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
37df0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
37e00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
37e10 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
37e20 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
37e30 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
37e40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
37e50 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
37e60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37e70 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
37e80 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
37e90 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
37ea0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
37eb0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
37ec0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
37ed0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
37ee0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
37ef0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
37f00 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
37f10 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
37f20 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37f30 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
37f40 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
37f50 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
37f60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
37f70 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
37f80 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
37f90 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
37fa0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
37fb0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
37fc0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
37fd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37fe0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
37ff0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
38000 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
38010 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
38020 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
38030 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
38040 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
38050 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
38060 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
38070 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38080 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
38090 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
380a0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
380b0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
380c0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
380d0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
380e0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
380f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
38100 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
38110 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
38120 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
38130 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
38140 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
38150 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
38160 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
38170 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
38180 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
38190 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
381a0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
381b0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
381c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
381d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
381e0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
381f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
38200 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
38210 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72  ALL sqlite3_user
38220 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
38230 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
38240 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
38250 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
38260 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
38270 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
38280 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
38290 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
382a0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
382b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
382c0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
382d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
382e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
382f0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
38300 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
38310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
38320 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
38330 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
38340 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
38350 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
38360 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
38370 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
38380 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
38390 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
383a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
383b0 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  te3 *SQLITE_STDC
383c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ALL sqlite3_cont
383d0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
383e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
383f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38400 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
38410 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54  iary Data.** MET
38420 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
38430 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  text.**.** These
38440 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
38450 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
38460 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
38470 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
38480 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
38490 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
384a0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
384b0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
384c0 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
384d0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
384e0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
384f0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
38500 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
38510 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
38520 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
38530 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
38540 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
38550 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
38560 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
38570 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
38580 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
38590 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
385a0 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
385b0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
385c0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
385d0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
385e0 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
385f0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
38600 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
38610 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
38620 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
38630 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
38640 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
38650 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
38660 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
38670 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
38680 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
38690 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
386a0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
386b0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
386c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
386d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
386e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
386f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
38700 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
38710 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
38720 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
38730 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
38740 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
38750 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
38760 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
38770 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38780 6f 6e 2e 20 5e 49 6