System.Data.SQLite
Hex Artifact Content
Not logged in
          HomeFAQDownloadTimelineBranchesTicketsLogin
Download

Artifact 9c140b844f70b60a3f88da61042ec24789f15797:

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 30 2e 20 20  ersion 3.10.0.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d  e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72  ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56   options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c  C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20  d be done first 
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76  uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20  ent spurious.** 
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75  s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74  ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68  his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74  er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79   are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f   this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e  nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68  egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72  *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73  s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e  pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56  .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53  C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e  VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72  ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72  able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72  able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72  able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72  able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72  able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72  able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72  able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72  able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72  able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72  able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72  able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72  able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72  able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72  able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e  able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f  dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e  MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20  dif /* _MSVC_H_ 
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e  *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77  *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66  here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   in sqliteInt.h 
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57  al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65  vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a  le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54  15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57  is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f  ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64  ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e  efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56  EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20  xWorks.  Set up 
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79  things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a   for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b  #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70  s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d  thread.h>  /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63  algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ache */.#define 
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65  OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f  fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53  THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f  QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20  RECURSIVE_MUTEX 
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e  _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53  SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43  QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65  KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20  fine HAVE_UTIME 
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20  1.#else./* This 
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20  is not VxWorks. 
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 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 30 22 0a 23 64       "3.10.0".#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 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
3140: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
3150: 20 20 22 32 30 31 35 2d 31 32 2d 33 31 20 32 32    "2015-12-31 22
3160: 3a 32 39 3a 33 36 20 64 34 31 64 34 64 37 33 39  :29:36 d41d4d739
3170: 36 66 62 61 36 30 38 39 35 35 33 35 66 32 31 63  6fba60895535f21c
3180: 34 33 38 66 38 63 37 35 65 37 62 32 30 39 37 22  438f8c75e7b2097"
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 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
b3e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b3f0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
b400: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
b410: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
b420: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b430: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b440: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c  MITTED]].** No l
b450: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a  onger in use..**
b460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b470: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a  _FCNTL_SYNC]].**
b480: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b490: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20  TL_SYNC] opcode 
b4a0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
b4b0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
b4c0: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f  e and.** sent to
b4d0: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61   the VFS immedia
b4e0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20  tely before the 
b4f0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
b500: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20  invoked on a.** 
b510: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65  database file de
b520: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66  scriptor. Or, if
b530: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b540: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  d is not invoked
b550: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65   .** because the
b560: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67   user has config
b570: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68  ured SQLite with
b580: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e   .** [PRAGMA syn
b590: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
b5a0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
b5b0: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  F] it is invoked
b5c0: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66   in place .** of
b5d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b5e0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73  d. In most cases
b5f0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72  , the pointer ar
b600: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69  gument passed wi
b610: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d  th.** this file-
b620: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e  control is NULL.
b630: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
b640: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b650: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a  s being synced.*
b660: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d  * as part of a m
b670: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f  ulti-database co
b680: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65  mmit, the argume
b690: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e  nt points to a n
b6a0: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
b6b0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
b6c0: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ng the transacti
b6d0: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e  ons master-journ
b6e0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46  al file name. VF
b6f0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20  Ses that .** do 
b700: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
b710: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65  gnal should sile
b720: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b730: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b740: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64  tions .** should
b750: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
b760: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b770: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
b780: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
b790: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20  may .** disrupt 
b7a0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
b7b0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
b7c0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
b7d0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
b7e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b7f0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
b800: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b  SETWO]].** The [
b810: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b820: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70  MIT_PHASETWO] op
b830: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
b840: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
b850: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65  SQLite.** and se
b860: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66  nt to the VFS af
b870: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ter a transactio
b880: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69  n has been commi
b890: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  tted immediately
b8a0: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74  .** but before t
b8b0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75  he database is u
b8c0: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74  nlocked. VFSes t
b8d0: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  hat do not need 
b8e0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73  this signal.** s
b8f0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
b900: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
b910: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
b920: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a  should not call.
b930: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
b940: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
b950: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
b960: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
b970: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65  rupt the .** ope
b980: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
b990: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
b9a0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
b9b0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
b9c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b9d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
b9e0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b9f0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
ba00: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
ba10: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
ba20: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
ba30: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
ba40: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
ba50: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
ba60: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
ba70: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
ba80: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
ba90: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
baa0: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
bab0: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
bac0: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
bad0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
bae0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
baf0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
bb00: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
bb10: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
bb20: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
bb30: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
bb40: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
bb50: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
bb60: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
bb70: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
bb80: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
bb90: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
bba0: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
bbb0: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
bbc0: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
bbd0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bbe0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
bbf0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
bc00: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
bc10: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
bc20: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
bc30: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
bc40: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
bc50: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
bc60: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
bc70: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
bc80: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
bc90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
bca0: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
bcb0: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
bcc0: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
bcd0: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
bce0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
bcf0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
bd00: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
bd10: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
bd20: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
bd30: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
bd40: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
bd50: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
bd60: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
bd70: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
bd80: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
bd90: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
bda0: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
bdb0: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
bdc0: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
bdd0: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
bde0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
bdf0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
be00: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
be10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be20: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
be30: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
be40: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
be50: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
be60: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
be70: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
be80: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
be90: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
bea0: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
beb0: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
bec0: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
bed0: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
bee0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
bef0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
bf00: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
bf10: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
bf20: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
bf30: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
bf40: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
bf50: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
bf60: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
bf70: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
bf80: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
bf90: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
bfa0: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
bfb0: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
bfc0: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
bfd0: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
bfe0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
bff0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
c000: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
c010: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
c020: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
c030: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
c040: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
c050: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
c060: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
c070: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
c080: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
c090: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
c0a0: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
c0b0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
c0c0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
c0d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c0e0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
c0f0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
c100: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
c110: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
c120: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
c130: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
c140: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
c150: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
c160: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
c170: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c180: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c190: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c1a0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c1b0: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
c1c0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
c1d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c1e0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
c1f0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
c200: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c210: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c220: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
c230: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
c240: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
c250: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
c260: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
c270: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
c280: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
c290: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
c2a0: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
c2b0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c2c0: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
c2d0: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
c2e0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
c2f0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
c300: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
c310: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c320: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
c330: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
c340: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c350: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
c360: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
c370: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
c380: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
c390: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
c3a0: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
c3b0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c3c0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c3d0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c3e0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c3f0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
c400: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
c410: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c420: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
c430: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c440: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
c450: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
c460: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
c470: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
c480: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
c490: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c4a0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
c4b0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
c4c0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
c4d0: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
c4e0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
c4f0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
c500: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
c510: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
c520: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
c530: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
c540: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c550: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c560: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c580: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c590: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c5a0: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
c5b0: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
c5c0: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
c5d0: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
c5e0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
c5f0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
c600: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
c610: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
c620: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
c630: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
c640: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
c650: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
c660: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
c670: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
c680: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
c690: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
c6a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c6b0: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
c6c0: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
c6d0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
c6e0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
c6f0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
c700: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
c710: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
c720: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
c730: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
c740: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
c750: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
c760: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
c770: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
c780: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
c790: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
c7a0: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
c7b0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
c7c0: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
c7d0: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
c7e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
c7f0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
c800: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
c810: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c820: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
c830: 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TER]].** ^The [S
c840: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c850: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
c860: 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20  finds a pointer 
c870: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
c880: 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72  .** [VFSes] curr
c890: 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e  ently in use.  ^
c8a0: 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20  (The argument X 
c8b0: 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  in.** sqlite3_fi
c8c0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51  le_control(db,SQ
c8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
c8e0: 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62  OINTER,X) must b
c8f0: 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73  e.** of type "[s
c900: 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e  qlite3_vfs] **".
c910: 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77    This opcodes w
c920: 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f  ill set *X.** to
c930: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
c940: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e  e top-level VFS.
c950: 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72  )^.** ^When ther
c960: 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56  e are multiple V
c970: 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20  FS shims in the 
c980: 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f  stack, this opco
c990: 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20  de finds the.** 
c9a0: 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20  upper-most shim 
c9b0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
c9c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
c9d0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
c9e0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
c9f0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
ca00: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
ca10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
ca20: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
ca30: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
ca40: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
ca50: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
ca60: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
ca70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
ca80: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
ca90: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
caa0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
cab0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
cac0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cad0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
cae0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
caf0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
cb00: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
cb10: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
cb20: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
cb30: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
cb40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
cb50: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
cb60: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
cb70: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
cb80: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
cb90: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
cba0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
cbb0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
cbc0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
cbe0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
cbf0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
cc00: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
cc10: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
cc20: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
cc30: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
cc40: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
cc50: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
cc60: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
cc70: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
cc80: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
cc90: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
cca0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
ccb0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
ccc0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
ccd0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
cce0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
ccf0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
cd00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
cd10: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
cd20: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
cd30: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
cd40: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
cd50: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
cd60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
cd70: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
cd80: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
cd90: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
cda0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
cdb0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
cdc0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
cdd0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
cde0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
cdf0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
ce00: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
ce10: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
ce20: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
ce30: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
ce40: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
ce50: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
ce60: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
ce70: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
ce80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ce90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
cea0: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
ceb0: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
cec0: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
ced0: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
cee0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
cef0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
cf00: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
cf10: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
cf20: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
cf30: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
cf40: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
cf50: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
cf60: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
cf70: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
cf80: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
cf90: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
cfa0: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
cfb0: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
cfc0: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
cfd0: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
cfe0: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
cff0: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
d000: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
d010: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
d020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
d030: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
d040: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
d050: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
d060: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
d070: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
d080: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
d090: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
d0a0: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
d0b0: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
d0c0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
d0d0: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
d0e0: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
d0f0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
d100: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
d110: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
d120: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
d130: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
d140: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
d150: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
d160: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
d170: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
d180: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
d190: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
d1a0: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
d1b0: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
d1c0: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
d1d0: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
d1e0: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
d1f0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
d200: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
d210: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
d220: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
d230: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
d240: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
d250: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
d260: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
d270: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
d280: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
d290: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
d2a0: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
d2b0: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
d2c0: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
d2d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d2e0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
d2f0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
d300: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
d310: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
d320: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d330: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
d340: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
d350: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
d360: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
d370: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
d380: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
d390: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
d3a0: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
d3b0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
d3c0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
d3d0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
d3e0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
d3f0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d400: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
d410: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
d420: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
d430: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
d440: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
d450: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
d460: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
d470: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
d480: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
d490: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
d4a0: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
d4b0: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
d4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d4d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
d4e0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
d4f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
d500: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
d510: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
d520: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
d530: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
d540: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
d550: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
d560: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
d570: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
d580: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
d590: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
d5a0: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
d5b0: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
d5c0: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
d5d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d5e0: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
d5f0: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
d600: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
d610: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
d620: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
d630: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
d640: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
d650: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
d660: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
d670: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
d680: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
d690: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
d6a0: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
d6b0: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
d6c0: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
d6d0: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
d6e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
d6f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
d700: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
d710: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
d720: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d730: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
d740: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d750: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
d760: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
d770: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
d780: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
d790: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
d7a0: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
d7b0: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
d7c0: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
d7d0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
d7e0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
d7f0: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
d800: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
d810: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
d820: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
d830: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
d840: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
d850: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
d860: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
d870: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
d880: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
d890: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
d8a0: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
d8b0: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
d8c0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
d8d0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
d8e0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
d8f0: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
d900: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d910: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
d920: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
d930: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
d940: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
d950: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
d960: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
d970: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
d980: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
d990: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
d9a0: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
d9b0: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
d9c0: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
d9d0: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
d9e0: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
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 57 49 4e 33 32  LITE_FCNTL_WIN32
da10: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
da20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
da30: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
da40: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
da50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
da60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
da70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
da80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
da90: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
daa0: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
dab0: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
dac0: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
dad0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
dae0: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
daf0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
db00: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
db10: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
db20: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
db30: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
db40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
db50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
db60: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
db70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
db80: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
db90: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
dba0: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
dbb0: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
dbc0: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
dbd0: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
dbe0: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
dbf0: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
dc00: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
dc10: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
dc20: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
dc30: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
dc40: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
dc50: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
dc60: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
dc70: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
dc80: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
dc90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
dca0: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
dcb0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
dcc0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
dcd0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
dce0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
dcf0: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20  E_FCNTL_ZIPVFS] 
dd00: 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d  opcode is implem
dd10: 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20  ented by zipvfs 
dd20: 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a  only. All other.
dd30: 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  ** VFS should re
dd40: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
dd50: 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70  OUND for this op
dd60: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  code..**.** <li>
dd70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52  [[SQLITE_FCNTL_R
dd80: 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  BU]].** The [SQL
dd90: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f  ITE_FCNTL_RBU] o
dda0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
ddb0: 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63  nted by the spec
ddc0: 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a  ial VFS used by.
ddd0: 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e  ** the RBU exten
dde0: 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  sion only.  All 
ddf0: 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64  other VFS should
de00: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
de10: 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74  OTFOUND for.** t
de20: 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a  his opcode.  .**
de30: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
de40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
de50: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
de60: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
de70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
de80: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
de90: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
dea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
deb0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
dec0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
ded0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
dee0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
def0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
df00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
df10: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
df20: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
df30: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
df40: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
df50: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
df60: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
df70: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
df80: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
df90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
dfa0: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
dfb0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
dfc0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
dfd0: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
dfe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dff0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
e000: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
e010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e020: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
e030: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
e040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e050: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
e060: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
e070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e080: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
e090: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
e0a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e0b0: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
e0c0: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
e0d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e0e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
e0f0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
e100: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e110: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
e120: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
e130: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
e140: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
e150: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
e160: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
e170: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
e180: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
e190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
e1a0: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
e1b0: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
e1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
e1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
e1e0: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
e1f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
e200: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
e210: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
e220: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
e230: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
e240: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
e250: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
e260: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
e270: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
e280: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
e290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
e2a0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
e2b0: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
e2c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
e2d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e2e0: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
e2f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
e300: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
e310: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
e320: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
e330: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
e340: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
e350: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
e360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
e370: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
e380: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
e390: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
e3a0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
e3b0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
e3c0: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
e3d0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
e3e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e3f0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
e400: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
e410: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
e420: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
e430: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
e440: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
e450: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
e460: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
e470: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
e480: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
e490: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
e4a0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
e4b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
e4c0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
e4d0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
e4e0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
e4f0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
e500: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
e510: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
e520: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
e530: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
e540: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
e550: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
e560: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
e570: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
e580: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
e590: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
e5a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e5b0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
e5c0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
e5d0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
e5e0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
e5f0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
e600: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
e610: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
e620: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
e630: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
e640: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
e650: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
e660: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
e670: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
e680: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
e690: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
e6a0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
e6b0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
e6c0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
e6d0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
e6e0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
e6f0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
e700: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e710: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
e720: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
e730: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
e740: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
e750: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
e760: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
e770: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
e780: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
e790: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
e7a0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
e7b0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
e7c0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
e7d0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
e7e0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
e7f0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
e800: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
e810: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
e820: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
e830: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
e840: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
e850: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
e860: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
e870: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
e880: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
e890: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
e8a0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
e8b0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
e8c0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
e8d0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
e8e0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
e8f0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
e900: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
e910: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
e920: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
e930: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
e940: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
e950: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
e960: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
e970: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
e980: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
e990: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
e9a0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
e9b0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
e9c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e9d0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
e9e0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
e9f0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
ea00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ea10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ea20: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
ea30: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ea40: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
ea50: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ea60: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
ea70: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
ea80: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
ea90: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
eaa0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
eab0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
eac0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
ead0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
eae0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
eaf0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
eb00: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
eb10: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
eb20: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
eb30: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
eb40: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
eb50: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
eb60: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
eb70: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
eb80: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
eb90: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
eba0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
ebb0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
ebc0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
ebd0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
ebe0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
ebf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
ec00: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
ec10: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
ec20: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
ec30: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
ec40: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
ec50: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
ec60: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
ec70: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
ec80: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
ec90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
eca0: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
ecb0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
ecc0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
ecd0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
ece0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
ecf0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
ed00: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
ed10: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
ed20: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
ed30: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
ed40: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
ed50: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
ed60: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
ed70: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
ed80: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ed90: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
eda0: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
edb0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
edc0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
edd0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ede0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
edf0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
ee00: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
ee10: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
ee20: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
ee30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
ee40: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
ee50: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
ee60: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
ee70: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
ee80: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
ee90: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
eea0: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
eeb0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
eec0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
eed0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
eee0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
eef0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
ef00: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
ef10: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
ef20: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
ef30: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
ef40: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
ef50: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
ef60: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
ef70: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
ef80: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
ef90: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
efa0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
efb0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
efc0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
efd0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
efe0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
eff0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
f000: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
f010: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
f020: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
f030: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
f040: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
f050: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
f060: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
f070: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
f080: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
f090: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
f0a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
f0b0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
f0c0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
f0d0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
f0e0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
f0f0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
f100: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
f110: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
f120: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
f130: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
f140: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f150: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
f160: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
f170: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
f180: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
f190: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
f1a0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
f1b0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
f1c0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
f1d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
f1e0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
f1f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
f200: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
f210: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
f220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
f230: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
f240: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
f250: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
f260: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
f270: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
f280: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
f290: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
f2a0: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
f2b0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
f2c0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
f2d0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
f2e0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
f2f0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
f300: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
f310: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
f320: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
f330: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
f340: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
f350: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
f360: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
f370: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
f380: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
f390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
f3a0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
f3b0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
f3c0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
f3d0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
f3e0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
f3f0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
f400: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
f410: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
f420: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
f430: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
f440: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
f450: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
f460: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
f470: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
f480: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
f490: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
f4a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
f4b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
f4c0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
f4d0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
f4e0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
f4f0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
f500: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
f510: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
f520: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
f530: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
f540: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
f550: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
f560: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
f570: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
f580: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
f590: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
f5a0: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
f5b0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
f5c0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
f5d0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
f5e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
f5f0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
f600: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
f610: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
f620: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
f630: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
f640: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
f650: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
f660: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
f670: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
f680: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
f690: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
f6a0: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
f6b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
f6c0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
f6d0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
f6e0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
f6f0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
f700: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
f710: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
f720: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
f730: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
f740: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
f750: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
f760: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
f770: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f780: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
f790: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
f7a0: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
f7b0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
f7c0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
f7d0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
f7e0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
f7f0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
f800: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
f810: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
f820: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
f830: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
f840: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
f850: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
f860: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
f870: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
f880: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
f890: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
f8a0: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
f8b0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
f8c0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
f8d0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
f8e0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
f8f0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
f900: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
f910: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
f920: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
f930: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
f940: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
f950: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
f960: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
f970: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
f980: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
f990: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
f9a0: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
f9b0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
f9c0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
f9d0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
f9e0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
f9f0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
fa00: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
fa10: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
fa20: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
fa30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
fa40: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
fa50: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
fa60: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
fa70: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
fa80: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
fa90: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
faa0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
fab0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
fac0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
fad0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
fae0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
faf0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
fb00: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
fb10: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
fb20: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
fb30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
fb40: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
fb50: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
fb60: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
fb70: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
fb80: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
fb90: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
fba0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
fbb0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
fbc0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
fbd0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
fbe0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
fbf0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
fc00: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
fc10: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
fc20: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
fc30: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
fc40: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
fc50: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
fc60: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
fc70: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
fc80: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
fc90: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
fca0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
fcb0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
fcc0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
fcd0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
fce0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
fcf0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
fd00: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
fd10: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
fd20: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
fd30: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
fd40: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
fd50: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
fd60: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
fd70: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
fd80: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
fd90: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
fda0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
fdb0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
fdc0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
fdd0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
fde0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
fdf0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
fe00: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
fe10: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
fe20: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
fe30: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
fe40: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
fe50: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
fe60: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
fe70: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
fe80: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
fe90: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
fea0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
feb0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
fec0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
fed0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
fee0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
fef0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
ff00: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
ff10: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
ff20: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
ff30: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
ff40: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
ff50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
ff60: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
ff70: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
ff80: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
ff90: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
ffa0: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
ffb0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
ffc0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
ffd0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
ffe0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
fff0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
10000 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
10010 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
10020 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
10030 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
10040 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
10050 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
10060 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
10070 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
10080 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
10090 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
100a0 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
100b0 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
100c0 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
100d0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
100e0 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
100f0 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
10100 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
10110 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
10120 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
10130 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
10140 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
10150 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
10160 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
10170 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
10180 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
10190 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
101a0 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
101b0 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
101c0 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
101d0 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
101e0 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
101f0 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
10200 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
10210 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
10220 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
10230 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
10240 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
10250 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
10260 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
10270 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
10280 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
10290 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
102a0 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
102b0 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
102c0 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
102d0 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
102e0 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
102f0 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
10300 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
10310 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
10320 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
10330 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
10340 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
10350 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
10360 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
10370 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
10380 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
10390 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
103a0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
103b0 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
103c0 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
103d0 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
103e0 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
103f0 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
10400 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
10410 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
10420 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
10430 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
10440 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
10450 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
10460 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
10470 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
10480 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
10490 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
104a0 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
104b0 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
104c0 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
104d0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
104e0 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
104f0 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
10500 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
10510 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
10520 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
10530 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
10540 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
10550 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
10560 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
10570 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
10580 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
10590 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
105a0 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
105b0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
105c0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
105d0 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
105e0 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
105f0 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
10600 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
10610 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
10620 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
10630 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
10640 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
10650 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
10660 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
10670 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
10680 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10690 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
106a0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
106b0 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
106c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
106d0 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
106e0 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
106f0 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
10700 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
10710 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10720 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
10730 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
10740 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
10750 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10760 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
10770 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
10780 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
10790 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
107a0 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
107b0 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
107c0 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
107d0 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
107e0 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
107f0 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
10800 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
10810 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
10820 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
10830 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
10840 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
10850 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
10860 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
10870 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
10880 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
10890 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
108a0 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
108b0 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
108c0 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
108d0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
108e0 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
108f0 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
10900 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
10910 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
10920 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
10930 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
10940 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
10950 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
10960 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
10970 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
10980 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
10990 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
109a0 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
109b0 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
109c0 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
109d0 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
109e0 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
109f0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
10a00 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
10a10 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
10a20 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
10a30 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
10a40 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
10a50 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10a60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10a70 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
10a80 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
10a90 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
10aa0 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
10ab0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10ac0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10ad0 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
10ae0 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
10af0 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
10b00 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10b10 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
10b20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
10b30 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
10b40 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
10b50 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
10b60 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
10b70 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
10b80 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
10b90 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
10ba0 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
10bb0 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
10bc0 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
10bd0 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
10be0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
10bf0 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
10c00 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
10c10 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10c20 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10c30 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
10c40 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
10c50 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
10c60 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
10c70 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
10c80 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
10c90 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
10ca0 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
10cb0 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
10cc0 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
10cd0 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
10ce0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10cf0 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
10d00 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
10d10 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
10d20 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
10d30 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
10d40 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10d50 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
10d60 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10d70 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10d80 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
10d90 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
10da0 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
10db0 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
10dc0 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
10dd0 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
10de0 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
10df0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
10e00 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
10e10 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10e20 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
10e30 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
10e40 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
10e50 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
10e60 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
10e70 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
10e80 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
10e90 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
10ea0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
10eb0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
10ec0 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
10ed0 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
10ee0 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
10ef0 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
10f00 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
10f10 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
10f20 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
10f30 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
10f40 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
10f50 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
10f60 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
10f70 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
10f80 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
10f90 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
10fa0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
10fb0 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
10fc0 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
10fd0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10fe0 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
10ff0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
11000 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
11010 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
11020 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
11030 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
11040 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
11050 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
11060 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
11070 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
11080 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
11090 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
110a0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
110b0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
110c0 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
110d0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
110e0 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
110f0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
11100 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
11110 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
11120 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
11130 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
11140 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
11150 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
11160 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
11170 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
11180 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
11190 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
111a0 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
111b0 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
111c0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
111d0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
111e0 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
111f0 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
11200 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
11210 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
11220 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
11230 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
11240 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
11250 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
11260 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
11270 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
11280 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
11290 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
112a0 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
112b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
112c0 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
112d0 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
112e0 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
112f0 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
11300 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
11310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11320 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
11330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11340 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
11350 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
11360 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
11370 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
11380 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
11390 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
113a0 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
113b0 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
113c0 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
113d0 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
113e0 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
113f0 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
11400 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
11410 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
11420 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
11430 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
11440 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
11450 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
11460 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
11470 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
11480 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
11490 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
114a0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
114b0 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
114c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
114d0 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
114e0 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
114f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
11500 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
11510 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
11520 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
11530 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
11540 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11550 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
11560 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
11570 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
11580 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
11590 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
115a0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
115b0 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
115c0 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
115d0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
115e0 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
115f0 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
11600 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
11610 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
11620 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
11630 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
11640 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
11650 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
11660 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
11670 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11680 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11690 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
116a0 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
116b0 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
116c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
116d0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
116e0 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
116f0 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
11700 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
11710 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
11720 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
11730 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
11740 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
11750 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
11760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
11770 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
11780 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
11790 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
117a0 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
117b0 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
117c0 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
117d0 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
117e0 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
117f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11800 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
11810 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
11820 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
11830 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
11840 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11850 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
11860 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11870 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
11880 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
11890 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
118a0 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
118b0 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
118c0 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
118d0 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
118e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
118f0 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
11900 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
11910 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
11920 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
11930 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
11940 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
11950 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
11960 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
11970 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
11980 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
11990 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
119a0 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
119b0 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
119c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
119d0 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
119e0 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
119f0 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
11a00 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
11a10 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
11a20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
11a30 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11a40 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
11a50 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
11a60 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11a70 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
11a80 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
11a90 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
11aa0 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
11ab0 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
11ac0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
11ad0 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
11ae0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11af0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
11b00 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
11b10 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
11b20 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
11b30 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
11b40 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
11b50 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
11b60 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
11b70 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
11b80 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
11b90 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
11ba0 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
11bb0 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
11bc0 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
11bd0 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
11be0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
11bf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
11c00 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
11c10 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
11c20 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
11c30 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
11c40 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
11c50 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
11c60 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
11c70 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
11c80 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11c90 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
11ca0 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
11cb0 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
11cc0 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
11cd0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11ce0 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
11cf0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
11d00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
11d10 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
11d20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
11d30 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
11d40 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
11d50 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
11d60 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
11d70 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
11d80 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
11d90 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
11da0 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
11db0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
11dc0 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
11dd0 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
11de0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11df0 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
11e00 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
11e10 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
11e20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11e30 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
11e40 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
11e50 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
11e60 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
11e70 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
11e80 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
11e90 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
11ea0 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
11eb0 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
11ec0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
11ed0 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
11ee0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
11ef0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11f00 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
11f10 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
11f20 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
11f30 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
11f40 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
11f50 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
11f60 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
11f70 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
11f80 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
11f90 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
11fa0 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
11fb0 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
11fc0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
11fd0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
11fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11ff0 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
12000 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
12010 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
12020 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12030 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
12040 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
12050 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
12060 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
12070 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
12080 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
12090 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
120a0 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
120b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
120c0 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
120d0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
120e0 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
120f0 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
12100 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
12110 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
12120 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
12130 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
12140 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
12150 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
12160 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
12170 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
12180 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
12190 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
121a0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
121b0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
121c0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
121d0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
121e0 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
121f0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
12200 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
12210 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
12220 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
12230 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
12240 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
12250 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
12260 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
12270 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
12280 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
12290 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
122a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
122b0 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
122c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
122d0 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
122e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
122f0 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
12300 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
12310 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
12320 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
12330 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
12340 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
12350 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
12360 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
12370 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
12380 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
12390 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
123a0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
123b0 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
123c0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
123d0 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
123e0 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
123f0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
12400 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
12410 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
12420 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
12430 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
12440 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
12450 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
12460 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
12470 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
12480 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
12490 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
124a0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
124b0 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
124c0 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
124d0 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
124e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
124f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
12500 4c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  L sqlite3_initia
12510 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
12520 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12530 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
12540 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
12550 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
12560 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
12570 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12580 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
12590 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
125a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f  CALL sqlite3_os_
125b0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
125c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
125d0 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
125e0 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
125f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
12600 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
12610 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
12620 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
12630 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
12640 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
12650 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
12660 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
12670 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
12680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
12690 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
126a0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
126b0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
126c0 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
126d0 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
126e0 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
126f0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
12700 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
12710 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
12720 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
12730 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
12740 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
12750 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12760 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
12770 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
12780 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
12790 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
127a0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
127b0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
127c0 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
127d0 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
127e0 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
127f0 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
12800 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
12810 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12820 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
12830 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
12840 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
12850 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
12860 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
12870 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
12880 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
12890 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
128a0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
128b0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
128c0 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
128d0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
128e0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
128f0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
12900 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
12910 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
12920 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
12930 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
12940 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
12950 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
12960 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
12970 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
12980 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
12990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
129a0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
129b0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
129c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
129d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
129e0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
129f0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
12a00 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
12a10 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
12a20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
12a30 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
12a40 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
12a50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
12a60 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
12a70 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
12a80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12a90 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
12aa0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
12ab0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
12ac0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12ad0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
12ae0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
12af0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
12b00 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
12b10 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
12b20 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
12b30 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
12b40 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
12b50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
12b60 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
12b70 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
12b80 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12b90 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f  CDECL sqlite3_co
12ba0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
12bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12bc0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
12bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
12be0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
12bf0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
12c00 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12c10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
12c20 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
12c30 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
12c40 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
12c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
12c60 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
12c70 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
12c80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12c90 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
12ca0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
12cb0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
12cc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12cd0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
12ce0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12cf0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
12d00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12d10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
12d20 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
12d30 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
12d40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12d50 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
12d60 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
12d70 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
12d80 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
12d90 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
12da0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
12db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
12dc0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
12dd0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
12de0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
12df0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
12e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
12e10 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
12e20 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
12e30 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
12e40 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
12e50 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
12e60 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
12e70 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
12e80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
12e90 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
12ea0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
12eb0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
12ec0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
12ed0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
12ee0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
12ef0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12f00 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12f10 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12f20 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12f30 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12f40 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12f50 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12f60 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12f70 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
12f80 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
12f90 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
12fa0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
12fb0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12fc0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12fd0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
12fe0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
12ff0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
13000 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
13010 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
13020 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13030 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
13040 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13050 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
13060 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
13070 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
13080 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
13090 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
130a0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
130b0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
130c0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
130d0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
130e0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
130f0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
13100 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
13110 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
13120 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
13130 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13140 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
13150 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
13160 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
13170 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
13180 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
13190 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
131a0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
131b0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
131c0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
131d0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
131e0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
131f0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
13200 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
13210 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
13220 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
13230 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
13240 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
13250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13260 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
13270 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
13280 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
13290 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
132a0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
132b0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
132c0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
132d0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
132e0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
132f0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
13300 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
13310 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
13320 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
13330 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
13340 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
13350 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
13360 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
13370 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
13380 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
13390 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
133a0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
133b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
133c0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
133d0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
133e0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
133f0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
13400 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13410 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
13420 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
13430 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
13440 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
13450 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
13460 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
13470 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
13480 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
13490 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
134a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
134b0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
134c0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
134d0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
134e0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
134f0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
13500 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
13510 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
13520 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
13530 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
13540 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
13550 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
13560 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
13570 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
13580 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
13590 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
135a0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
135b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
135c0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
135d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
135e0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
135f0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
13600 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
13610 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
13620 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
13630 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
13640 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
13650 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
13660 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
13670 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
13680 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13690 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
136a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
136b0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
136c0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
136d0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
136e0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
136f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
13700 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
13710 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
13720 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
13730 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
13740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
13750 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
13760 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
13770 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
13780 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
13790 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
137a0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
137b0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
137c0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
137d0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
137e0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
137f0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
13800 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
13810 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
13820 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
13830 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
13840 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
13850 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
13860 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
13870 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
13880 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
13890 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
138a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
138b0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
138c0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
138d0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
138e0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
138f0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
13900 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
13910 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
13920 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
13930 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
13940 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
13950 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
13960 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
13970 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
13980 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
13990 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
139a0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
139b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
139c0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
139d0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
139e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
139f0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
13a00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
13a10 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
13a20 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
13a30 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
13a40 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
13a50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
13a60 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
13a70 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
13a80 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
13a90 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
13aa0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
13ab0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
13ac0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
13ad0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
13ae0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
13af0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
13b00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
13b10 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
13b20 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
13b30 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
13b40 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
13b50 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
13b60 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
13b70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
13b80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
13b90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
13ba0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
13bb0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
13bc0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
13bd0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
13be0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
13bf0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
13c00 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
13c10 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
13c20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
13c30 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
13c40 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
13c50 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
13c60 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
13c70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
13c80 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
13c90 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
13ca0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
13cb0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
13cc0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
13cd0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
13ce0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
13cf0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
13d00 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
13d10 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
13d20 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
13d30 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
13d40 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13d50 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13d60 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
13d70 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
13d80 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
13d90 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
13da0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
13db0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
13dc0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
13dd0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
13de0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
13df0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
13e00 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
13e10 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
13e20 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
13e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
13e40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
13e50 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
13e60 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
13e70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13e80 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
13e90 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
13ea0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13eb0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
13ec0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
13ed0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
13ee0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13ef0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13f00 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13f10 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13f20 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13f30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13f40 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13f50 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13f60 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13f70 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13f80 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
13f90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13fa0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
13fb0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
13fc0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
13fd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
13fe0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13ff0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
14000 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
14010 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
14020 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
14030 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14040 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
14050 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
14060 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14070 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
14080 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14090 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
140b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
140c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
140d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
140e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
140f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
14100 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
14110 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14120 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14130 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
14140 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
14150 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
14160 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
14170 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
14180 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
14190 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
141a0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
141b0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
141c0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
141d0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
141e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
141f0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14200 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
14210 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
14220 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
14230 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
14240 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
14250 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
14260 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14270 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
14280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
14290 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
142a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
142b0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
142c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
142d0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
142e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
142f0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
14300 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14310 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
14320 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
14330 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
14340 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
14350 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14360 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14370 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
14380 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
14390 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
143a0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
143b0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
143c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
143d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
143e0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
143f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
14400 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
14410 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
14420 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
14430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14440 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
14450 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
14460 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
14470 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
14480 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
14490 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
144a0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
144b0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
144c0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
144d0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
144e0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
144f0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
14500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14510 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
14520 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
14530 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14540 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
14550 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
14560 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
14570 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14580 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
14590 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
145a0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
145b0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
145c0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
145d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
145e0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
145f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14600 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
14610 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
14620 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
14630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14640 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
14650 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14660 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
14680 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
14690 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
146a0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
146b0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
146c0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
146d0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
146e0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
146f0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
14700 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
14710 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
14720 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
14730 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
14740 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
14750 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14760 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
14770 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
14780 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
14790 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
147a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
147b0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
147c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
147d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
147e0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
147f0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
14800 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
14810 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
14820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
14830 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14840 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
14850 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
14860 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
14870 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
14880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14890 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
148a0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
148b0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
148c0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
148d0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
148e0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
148f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14900 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14910 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14920 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14930 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14940 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14950 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14960 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
14970 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
14980 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
14990 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
149a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
149b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
149c0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
149d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
149e0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
149f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
14a00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14a10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14a20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14a30 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
14a40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14a50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14a60 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14a70 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14a80 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14a90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14aa0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14ab0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
14ac0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
14ad0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
14ae0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
14af0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
14b00 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
14b10 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
14b20 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
14b30 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
14b40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
14b50 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
14b60 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
14b70 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
14b80 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
14b90 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
14ba0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
14bb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
14bc0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
14bd0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
14be0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
14bf0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
14c00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14c10 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
14c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c30 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
14c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14c60 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14c70 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14c80 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14c90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14ca0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
14cb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
14cc0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14cd0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
14ce0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
14cf0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
14d00 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
14d10 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
14d20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14d30 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
14d40 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14d50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14d60 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14d70 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14d80 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
14d90 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
14da0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
14db0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14dc0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
14dd0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
14de0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
14df0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14e10 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
14e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14e30 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
14e40 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14e50 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
14e60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
14e70 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
14e80 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
14e90 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
14ea0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
14eb0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
14ec0 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
14ed0 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
14ee0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14ef0 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
14f00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14f10 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
14f20 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
14f30 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14f40 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
14f50 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
14f60 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
14f70 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14f80 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
14f90 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14fa0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14fb0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14fc0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14fd0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14fe0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14ff0 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
15000 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
15010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
15020 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
15030 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
15040 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
15050 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
15060 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
15070 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
15080 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
15090 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
150a0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
150b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
150c0 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
150d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
150e0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
150f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15100 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
15110 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
15120 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15130 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
15140 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
15150 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
15160 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
15170 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  for scratch memo
15180 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65  ry.  ^(There are
15190 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
151a0 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  .** to SQLITE_CO
151b0 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41  NFIG_SCRATCH:  A
151c0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
151d0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
151e0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
151f0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
15200 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
15210 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
15220 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
15230 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
15240 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
15250 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
15260 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
15270 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
15280 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  )^.** The first 
15290 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
152a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
152b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
152c0 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
152d0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
152e0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
152f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20  SQLite will not 
15300 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  use more than on
15310 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
15320 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a  s per thread..**
15330 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
15340 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
15350 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
15360 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
15370 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
15380 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
15390 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
153a0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
153b0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
153c0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
153d0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
153e0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
153f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
15400 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
15410 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
15420 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
15430 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
15440 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e  ded.<p>.** ^When
15450 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15460 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d   provides any am
15470 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20  ount of scratch 
15480 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20  memory using.** 
15490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
154a0 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76  RATCH, SQLite av
154b0 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79  oids unnecessary
154c0 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74   large.** [sqlit
154d0 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61  e3_malloc|heap a
154e0 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20  llocations]..** 
154f0 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52  This can help [R
15500 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76  obson proof|prev
15510 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ent memory alloc
15520 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20  ation failures] 
15530 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66  due to heap.** f
15540 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  ragmentation in 
15550 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64  low-memory embed
15560 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20  ded systems..** 
15570 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15590 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
155a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
155b0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
155c0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
155d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
155e0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
155f0 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
15600 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
15610 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
15620 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
15630 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
15640 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
15650 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
15660 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
15670 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
15680 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
15690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
156a0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
156b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
156c0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
156d0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
156e0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
156f0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15700 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15710 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15720 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
15730 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
15740 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
15750 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
15760 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
15770 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
15780 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
15790 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
157a0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
157b0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
157c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
157d0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
157e0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
157f0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
15800 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
15810 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
15820 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
15830 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
15840 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
15850 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
15860 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
15870 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
15880 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
158a0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
158b0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
158c0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
158d0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
158e0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
158f0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
15900 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
15910 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
15920 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15930 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
15940 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
15950 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
15960 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
15970 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
15980 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
15990 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
159a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
159b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
159c0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
159d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
159e0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
159f0 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
15a00 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
15a10 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
15a20 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
15a30 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
15a40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
15a50 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
15a60 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
15a70 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
15a80 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
15a90 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
15aa0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
15ab0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
15ac0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
15ad0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
15ae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15af0 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
15b00 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
15b10 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
15b20 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
15b30 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15b40 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
15b50 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
15b60 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
15b70 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
15b80 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
15b90 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
15ba0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
15bb0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
15bc0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
15bd0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
15be0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
15bf0 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
15c00 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
15c10 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
15c20 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
15c30 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
15c40 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
15c50 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
15c60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15c70 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
15c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15c90 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
15ca0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15cb0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
15cc0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
15cd0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
15ce0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
15cf0 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
15d00 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
15d10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15d20 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
15d30 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
15d40 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
15d50 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
15d60 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  nd.** [SQLITE_CO
15d70 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
15d80 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
15d90 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
15da0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
15db0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
15dc0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
15dd0 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
15de0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
15df0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
15e00 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
15e10 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
15e20 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
15e30 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
15e40 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
15e50 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
15e60 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
15e70 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
15e80 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
15e90 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
15ea0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
15eb0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
15ec0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
15ed0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
15ee0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
15ef0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
15f00 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
15f10 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
15f20 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
15f30 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
15f40 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
15f50 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
15f60 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
15f70 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
15f80 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
15f90 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
15fa0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
15fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15fc0 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
15fd0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
15fe0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
15ff0 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
16000 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
16010 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
16020 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
16030 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
16040 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16050 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
16060 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
16070 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
16080 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16090 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
160a0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
160b0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
160c0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
160d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
160e0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
160f0 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
16100 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
16110 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
16120 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
16130 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
16140 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
16150 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
16160 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16170 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
16180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16190 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
161a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
161b0 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
161c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
161d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
161e0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
161f0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
16200 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
16210 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
16220 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
16230 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
16240 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
16250 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
16260 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
16270 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
16280 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
16290 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
162a0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
162b0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
162c0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
162d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
162e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
162f0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
16300 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
16310 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
16320 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
16330 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
16340 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
16350 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
16360 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
16370 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
16380 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
16390 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
163a0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
163b0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
163c0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
163d0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
163e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
163f0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
16400 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16420 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
16430 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
16440 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
16450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
16460 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
16470 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16480 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
16490 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
164a0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
164b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
164c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
164d0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
164e0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
164f0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
16500 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16510 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
16520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
16530 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
16540 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
16550 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
16560 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
16570 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
16580 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
16590 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
165a0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
165b0 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
165c0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
165d0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
165e0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
165f0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
16600 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
16610 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
16620 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
16630 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
16640 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
16650 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
16660 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
16670 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
16680 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16690 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
166a0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
166b0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
166c0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
166d0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
166e0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
166f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
16700 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
16710 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
16720 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16730 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
16740 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
16750 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16760 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16770 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
16780 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16790 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
167a0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
167b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
167c0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
167d0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
167e0 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
167f0 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
16800 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16810 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
16820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
16830 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
16840 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
16850 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16860 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16870 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
16880 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16890 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
168a0 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
168b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
168c0 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
168d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
168e0 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
168f0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
16900 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
16910 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16920 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
16930 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
16940 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
16950 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
16960 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16970 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
16980 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
16990 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
169a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
169b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
169c0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
169d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
169e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
169f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a00 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
16a10 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16a20 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
16a30 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
16a40 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
16a50 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16a60 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
16a70 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
16a80 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
16a90 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
16aa0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
16ab0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
16ac0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
16ad0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
16ae0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
16af0 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
16b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16b10 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
16b20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16b30 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
16b40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
16b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16b60 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
16b70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16b80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
16b90 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16ba0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
16bb0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
16bc0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
16bd0 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
16be0 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
16bf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16c00 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
16c10 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
16c20 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16c30 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
16c40 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
16c50 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
16c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16c70 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16c80 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
16c90 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
16ca0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
16cb0 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
16cc0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
16cd0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
16ce0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
16cf0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
16d00 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
16d10 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
16d20 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
16d30 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
16d40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
16d50 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
16d60 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
16d70 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
16d80 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
16d90 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
16da0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
16db0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
16dc0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
16dd0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
16de0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
16df0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
16e00 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
16e10 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
16e20 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
16e30 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16e40 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
16e50 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
16e60 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
16e70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16e80 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
16e90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
16ea0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
16eb0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
16ec0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
16ed0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
16ee0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
16ef0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
16f00 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
16f10 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
16f20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
16f30 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
16f40 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
16f50 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
16f60 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
16f70 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
16f80 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
16f90 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
16fa0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16fb0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
16fc0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
16fd0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
16fe0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
16ff0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17000 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
17010 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
17020 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
17030 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
17040 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
17050 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
17060 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
17070 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
17080 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
17090 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
170a0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
170b0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
170c0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
170d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
170e0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
170f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
17100 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
17110 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
17120 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
17130 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
17140 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
17150 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17160 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
17170 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
17180 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
17190 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
171a0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
171b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
171c0 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
171d0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
171e0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
171f0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
17200 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
17210 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
17220 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
17230 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
17240 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
17250 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
17260 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
17270 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
17280 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
17290 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
172a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
172b0 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
172c0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
172d0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
172e0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
172f0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
17300 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
17310 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
17320 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
17330 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
17340 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
17350 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
17360 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
17370 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
17380 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
17390 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
173a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
173b0 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
173c0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
173d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
173e0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
173f0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
17400 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
17410 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
17420 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
17430 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
17440 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
17450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
17460 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
17470 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
17480 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
17490 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
174a0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
174b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
174c0 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
174d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
174e0 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
174f0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
17500 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
17510 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
17520 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17530 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
17540 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
17550 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
17560 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
17570 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
17580 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
17590 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
175a0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
175b0 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
175c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
175d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
175e0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
175f0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
17600 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17610 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
17620 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
17630 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
17640 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
17650 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
17660 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
17670 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
17680 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
17690 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
176a0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
176b0 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
176c0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
176d0 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
176e0 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
176f0 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
17700 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
17710 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
17720 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
17730 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
17740 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
17750 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
17760 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
17770 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
17780 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17790 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
177a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
177b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
177c0 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
177d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
177e0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
177f0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
17800 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
17810 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
17820 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
17830 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
17840 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
17850 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
17860 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
17870 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
17880 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17890 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
178a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
178b0 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
178c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
178d0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
178e0 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
178f0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
17900 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
17910 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
17920 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
17930 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
17940 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
17950 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
17960 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
17970 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
17980 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
17990 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
179a0 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
179b0 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
179c0 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
179d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
179e0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
179f0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
17a00 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
17a10 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
17a20 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
17a30 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
17a40 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
17a50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17a60 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
17a70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17a80 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
17a90 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
17aa0 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
17ab0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
17ac0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
17ad0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
17ae0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
17af0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
17b00 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
17b10 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
17b20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17b30 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
17b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
17b50 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
17b60 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
17b70 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
17b80 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
17b90 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
17ba0 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
17bb0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
17bc0 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
17bd0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17be0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
17bf0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
17c00 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
17c10 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
17c20 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
17c30 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
17c40 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
17c50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17c60 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
17c70 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
17c80 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
17c90 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
17ca0 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
17cb0 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
17cc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17cd0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
17ce0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17cf0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
17d00 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
17d10 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
17d20 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
17d30 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
17d40 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
17d50 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
17d60 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
17d70 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
17d80 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
17d90 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
17da0 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
17db0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
17dc0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
17dd0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
17de0 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
17df0 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
17e00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17e10 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
17e20 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
17e30 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
17e40 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
17e50 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17e60 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
17e70 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
17e80 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
17e90 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
17ea0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
17eb0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
17ec0 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
17ed0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
17ee0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
17ef0 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
17f00 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
17f10 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17f20 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
17f30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17f40 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
17f50 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
17f60 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
17f70 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
17f80 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
17f90 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
17fa0 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
17fb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
17fc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
17fd0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
17fe0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17ff0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
18000 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
18010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
18020 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
18030 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
18040 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
18050 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
18060 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
18070 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
18080 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
18090 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
180a0 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
180b0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
180c0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
180d0 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
180e0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
180f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
18100 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
18110 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
18120 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
18130 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18140 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
18150 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18160 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
18170 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
18180 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18190 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
181a0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
181b0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
181c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
181d0 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
181e0 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
181f0 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
18200 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
18210 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
18220 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
18230 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
18240 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
18250 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
18260 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
18270 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
18280 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
18290 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
182a0 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
182b0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
182c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
182d0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
182e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
182f0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
18300 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
18310 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
18320 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
18330 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
18340 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
18350 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
18360 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
18370 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
18380 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
18390 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
183a0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
183b0 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
183c0 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
183d0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
183e0 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
183f0 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
18400 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
18410 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
18420 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
18430 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
18440 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
18450 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
18460 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
18470 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
18480 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
18490 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
184a0 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
184b0 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
184c0 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
184d0 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
184e0 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
184f0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
18500 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
18510 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e   value..** </dl>
18520 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18530 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
18540 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
18550 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18560 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
18570 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
18580 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
185a0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
185b0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
185c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
185d0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
185e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
185f0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
18600 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
18610 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
18620 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
18630 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
18640 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18650 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
18660 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18670 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
18680 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18690 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
186a0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
186b0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
186c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
186d0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
186e0 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
186f0 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
18700 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
18710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
18720 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
18730 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
18740 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18750 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
18760 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
18770 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
18780 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18790 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
187a0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
187b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
187c0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
187d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
187e0 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
187f0 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
18800 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
18810 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18820 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
18830 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
18840 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18850 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
18860 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18880 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
18890 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
188a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
188b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
188c0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
188d0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
188e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
188f0 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
18900 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
18910 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18920 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
18930 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
18940 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
18950 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18960 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
18970 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
18980 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
18990 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
189a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
189b0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
189c0 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
189d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
189e0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
189f0 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
18a00 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
18a10 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18a20 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
18a30 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
18a40 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
18a50 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
18a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
18a70 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
18a80 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
18a90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18aa0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18ab0 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
18ac0 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
18ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18ae0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
18af0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
18b00 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
18b10 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  zPma */../*.** C
18b20 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
18b30 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
18b40 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
18b50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
18b60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
18b70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
18b80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
18b90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
18ba0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
18bb0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
18bc0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
18bd0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18be0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
18bf0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
18c00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
18c10 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
18c20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
18c30 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
18c40 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
18c50 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
18c60 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
18c70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
18c80 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
18c90 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
18ca0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
18cb0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
18cc0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
18cd0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
18ce0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
18cf0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
18d00 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
18d10 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
18d20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
18d30 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
18d40 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
18d50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
18d60 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
18d70 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
18d80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18d90 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
18da0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18db0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
18dc0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
18dd0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
18de0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
18df0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
18e00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
18e10 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
18e20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
18e30 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
18e40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18e50 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
18e60 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
18e70 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
18e80 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
18e90 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
18ea0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
18eb0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
18ec0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18ed0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
18ee0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18ef0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
18f00 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
18f10 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
18f20 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
18f30 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
18f40 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
18f50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
18f60 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
18f70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18f80 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
18f90 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
18fa0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
18fb0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
18fc0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
18fd0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
18fe0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
18ff0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
19000 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
19010 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
19020 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
19030 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
19040 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
19050 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
19060 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
19070 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
19080 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
19090 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
190a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
190b0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
190c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
190d0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
190e0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
190f0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
19100 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
19110 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
19120 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
19130 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19140 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
19150 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
19160 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
19170 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
19180 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
19190 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
191a0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
191b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
191c0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
191d0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
191e0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
191f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
19200 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
19210 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
19220 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
19230 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
19240 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
19250 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
19260 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
19270 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
19280 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
19290 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
192a0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
192b0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
192c0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
192d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
192e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
192f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19300 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
19310 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
19320 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
19330 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
19340 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
19350 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
19360 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
19370 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
19380 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19390 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
193a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
193b0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
193c0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
193d0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
193e0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
193f0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
19400 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
19410 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
19420 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
19430 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
19440 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19450 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19460 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
19470 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
19480 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19490 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
194a0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
194b0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
194c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
194d0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
194e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
194f0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
19500 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
19510 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
19520 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
19530 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
19540 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
19550 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
19560 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
19570 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
19580 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
19590 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
195a0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
195b0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
195c0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
195d0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
195e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
195f0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
19600 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
19610 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
19620 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
19630 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
19640 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19650 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
19660 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19670 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
19680 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
19690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
196a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
196b0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
196c0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
196d0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
196e0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
196f0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
19700 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
19710 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
19720 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
19730 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
19740 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
19750 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
19760 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
19770 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19780 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19790 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
197a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
197b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
197c0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
197d0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
197e0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
197f0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19800 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
19810 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
19820 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19830 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19840 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
19850 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
19860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19870 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
19880 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
19890 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
198a0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
198b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
198c0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
198d0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
198e0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
198f0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
19900 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
19910 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
19920 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
19930 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
19940 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
19950 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
19960 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
19970 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
19980 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
19990 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
199a0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
199b0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
199c0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
199d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
199e0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
199f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19a00 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
19a10 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
19a20 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
19a30 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
19a40 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
19a50 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
19a60 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
19a70 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
19a80 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
19a90 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
19aa0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
19ab0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
19ac0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
19ad0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
19ae0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
19af0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
19b00 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
19b10 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
19b20 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
19b30 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
19b40 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
19b50 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
19b60 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
19b70 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
19b80 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
19b90 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
19ba0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
19bb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19bc0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19bd0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
19be0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
19bf0 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
19c00 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
19c10 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
19c20 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
19c30 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
19c40 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
19c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
19c60 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
19c70 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
19c80 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
19c90 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
19ca0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
19cb0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
19cc0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
19cd0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
19ce0 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
19cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
19d00 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
19d10 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19d20 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
19d30 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
19d40 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
19d50 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
19d60 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
19d70 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
19d80 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
19d90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
19da0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
19db0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
19dc0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
19dd0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
19de0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
19df0 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
19e00 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
19e10 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
19e20 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
19e30 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
19e40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19e50 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
19e60 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
19e70 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
19e80 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
19e90 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
19ea0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
19eb0 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
19ec0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
19ed0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
19ee0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
19ef0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
19f00 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
19f10 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
19f20 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
19f30 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
19f40 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
19f50 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
19f60 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
19f70 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
19f80 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
19f90 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
19fa0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
19fb0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19fc0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
19fd0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
19fe0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
19ff0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1a000 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1a010 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1a020 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1a030 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1a040 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1a050 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1a060 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1a070 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1a080 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1a090 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1a0a0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1a0b0 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1a0c0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1a0d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1a0e0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1a0f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1a100 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1a110 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1a120 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1a130 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1a140 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1a150 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1a160 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1a170 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1a180 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1a190 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1a1a0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1a1b0 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1a1c0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1a1d0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1a1e0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1a1f0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1a200 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1a210 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1a220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1a230 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1a240 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a250 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1a260 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1a270 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1a280 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1a290 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1a2a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a2b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1a2c0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1a2d0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1a2e0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1a2f0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1a300 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1a310 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1a320 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51  t [rowid]..*/.SQ
1a330 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1a340 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
1a350 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61  DCALL sqlite3_la
1a360 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a370 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1a380 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
1a390 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
1a3a0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1a3b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a3c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1a3d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1a3e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a3f0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
1a400 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
1a410 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
1a420 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
1a430 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a440 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
1a450 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
1a460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a470 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
1a480 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1a490 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
1a4a0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1a4b0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a4c0 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
1a4d0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
1a4e0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
1a4f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
1a500 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
1a510 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
1a520 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
1a530 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1a540 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
1a550 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
1a560 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
1a570 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
1a580 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
1a590 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
1a5a0 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
1a5b0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1a5c0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1a5d0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1a5e0 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1a5f0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1a600 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1a610 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1a620 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1a630 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1a640 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a650 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1a660 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a670 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1a680 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1a690 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a6a0 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1a6b0 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1a6c0 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1a6d0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1a6e0 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1a6f0 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1a700 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1a710 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1a720 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1a730 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1a740 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1a750 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1a760 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1a770 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1a780 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1a790 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1a7a0 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1a7b0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1a7c0 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1a7d0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1a7e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1a7f0 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1a800 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1a810 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1a820 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1a830 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1a840 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1a850 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1a860 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1a870 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1a880 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1a890 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1a8a0 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1a8b0 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1a8c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1a8d0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1a8e0 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1a8f0 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1a900 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1a910 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1a920 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1a930 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1a940 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1a950 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1a960 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a970 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a980 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1a990 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1a9a0 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1a9b0 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1a9c0 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1a9d0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1a9e0 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1a9f0 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1aa00 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1aa10 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1aa20 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1aa30 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1aa40 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1aa50 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1aa60 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1aa70 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1aa80 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1aa90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1aaa0 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1aab0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1aac0 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1aad0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1aae0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1aaf0 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1ab00 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1ab10 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1ab20 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1ab30 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1ab40 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1ab50 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1ab60 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1ab70 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1ab80 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1ab90 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1aba0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1abb0 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1abc0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1abd0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1abe0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1abf0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1ac00 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1ac10 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1ac20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1ac30 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1ac40 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1ac50 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1ac60 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1ac70 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1ac80 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1ac90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1aca0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1acb0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1acc0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1acd0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1ace0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1acf0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1ad00 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1ad10 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1ad20 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1ad30 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1ad40 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1ad50 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
1ad60 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1ad70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  ALL sqlite3_chan
1ad80 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1ad90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ada0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1adb0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1adc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1add0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1ade0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1adf0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1ae00 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1ae10 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1ae20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1ae30 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1ae40 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1ae50 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1ae60 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1ae70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ae80 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1ae90 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1aea0 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1aeb0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1aec0 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1aed0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1aee0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1aef0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1af00 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1af10 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1af20 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1af30 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1af40 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1af50 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1af60 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1af70 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1af80 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1af90 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1afa0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1afb0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1afc0 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1afd0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1afe0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1aff0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1b000 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1b010 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1b020 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1b030 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1b040 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b050 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b060 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b070 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1b080 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1b090 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b0a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b0b0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1b0c0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1b0d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b0e0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1b0f0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b100 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1b110 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1b120 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1b130 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1b140 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1b150 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
1b160 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1b170 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  ALL sqlite3_tota
1b180 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
1b190 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1b1a0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
1b1b0 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
1b1c0 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
1b1d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1b1e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
1b1f0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1b200 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1b210 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1b220 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1b230 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1b240 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1b250 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1b260 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1b270 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1b280 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1b290 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1b2a0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1b2b0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1b2c0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1b2d0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1b2e0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1b2f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1b300 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1b310 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1b320 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1b330 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1b340 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1b350 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1b360 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1b370 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1b380 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1b390 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1b3a0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1b3b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b3c0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1b3d0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1b3e0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1b3f0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1b400 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1b410 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1b420 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1b430 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1b440 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1b450 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b460 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1b470 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1b480 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1b490 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1b4a0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1b4b0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1b4c0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1b4d0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1b4e0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1b4f0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1b500 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1b510 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1b520 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1b530 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1b540 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1b550 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1b560 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1b570 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1b580 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1b590 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1b5a0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1b5b0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1b5c0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1b5d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b5e0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1b5f0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1b600 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1b610 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1b620 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1b630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1b640 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1b650 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1b660 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1b670 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1b680 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b690 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1b6a0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1b6b0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1b6c0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1b6d0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1b6e0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1b6f0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1b700 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1b710 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1b720 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1b730 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1b740 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1b750 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1b760 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1b770 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1b780 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1b790 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1b7a0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1b7b0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1b7c0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1b7d0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1b7e0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1b7f0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1b800 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1b810 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1b820 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1b830 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1b840 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1b850 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1b860 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1b870 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
1b880 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b890 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
1b8a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
1b8b0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
1b8c0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
1b8d0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
1b8e0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
1b8f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
1b900 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1b910 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b920 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b930 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1b940 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1b950 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1b960 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1b970 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1b980 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1b990 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1b9a0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1b9b0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1b9c0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1b9d0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1b9e0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1b9f0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1ba00 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1ba10 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1ba20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1ba30 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1ba40 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1ba50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1ba60 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1ba70 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1ba80 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1ba90 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1baa0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1bab0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1bac0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1bad0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1bae0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1baf0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1bb00 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1bb10 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1bb20 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1bb30 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1bb40 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1bb50 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1bb60 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1bb70 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1bb80 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1bb90 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1bba0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1bbb0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1bbc0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1bbd0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1bbe0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1bbf0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1bc00 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1bc10 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1bc20 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1bc30 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1bc40 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1bc50 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1bc60 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1bc70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1bc80 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1bc90 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1bca0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1bcb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1bcc0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1bcd0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1bce0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1bcf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1bd00 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1bd10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1bd20 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1bd30 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1bd40 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1bd50 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1bd60 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1bd70 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1bd80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1bd90 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1bda0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1bdb0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1bdc0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1bdd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1bde0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1bdf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1be00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1be10 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1be20 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1be30 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1be40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1be50 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1be60 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1be70 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1be80 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1be90 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1bea0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1beb0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1bec0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1bed0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1bee0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1bef0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1bf00 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1bf10 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1bf20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1bf30 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1bf40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1bf50 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1bf60 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1bf70 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1bf80 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1bf90 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
1bfa0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
1bfb0 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   *sql);.SQLITE_A
1bfc0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
1bfd0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
1bfe0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
1bff0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
1c000 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
1c010 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
1c020 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
1c030 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20  _BUSY Errors.** 
1c040 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d  KEYWORDS: {busy-
1c050 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1c060 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d  } {busy handler}
1c070 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c080 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
1c090 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c0a0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
1c0b0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
1c0c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
1c0d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
1c0e0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
1c0f0 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
1c100 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
1c110 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1c120 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1c130 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c140 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c150 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
1c160 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
1c170 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
1c180 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
1c190 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1c1a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c1b0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
1c1c0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1c1d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
1c1e0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
1c1f0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1c200 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
1c210 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c220 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
1c230 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1c240 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1c250 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1c260 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1c270 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1c280 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1c290 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1c2a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1c2b0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1c2c0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1c2d0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1c2e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1c2f0 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1c300 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1c310 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1c320 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1c330 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1c340 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1c350 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1c360 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1c370 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1c380 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1c390 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1c3a0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1c3b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1c3c0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1c3d0 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f  ed previously fo
1c3e0 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
1c3f0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
1c400 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
1c410 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
1c420 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
1c430 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
1c440 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
1c450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1c460 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
1c470 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
1c480 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1c490 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
1c4a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1c4b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1c4c0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1c4d0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1c4e0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1c4f0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
1c500 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
1c510 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
1c520 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
1c530 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
1c540 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
1c550 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
1c560 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
1c570 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
1c580 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
1c590 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
1c5a0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
1c5b0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
1c5c0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
1c5d0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
1c5e0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
1c5f0 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
1c600 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
1c610 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
1c620 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
1c630 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
1c640 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
1c650 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
1c660 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
1c670 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
1c680 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
1c690 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
1c6a0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
1c6b0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
1c6c0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1c6d0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
1c6e0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
1c6f0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
1c700 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
1c710 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
1c720 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
1c730 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
1c740 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1c750 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
1c760 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1c770 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
1c780 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
1c790 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1c7a0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
1c7b0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
1c7c0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
1c7d0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
1c7e0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
1c7f0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
1c800 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
1c810 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
1c820 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
1c830 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
1c840 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
1c850 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
1c860 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
1c870 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
1c880 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
1c890 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
1c8a0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
1c8b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
1c8c0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
1c8d0 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
1c8e0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1c8f0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1c900 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
1c910 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
1c920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c930 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
1c940 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
1c950 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
1c960 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
1c970 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
1c980 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
1c990 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1c9a0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
1c9b0 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
1c9c0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
1c9d0 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
1c9e0 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
1c9f0 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
1ca00 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1ca10 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
1ca20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1ca30 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1ca40 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1ca50 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1ca60 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1ca70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1ca80 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1ca90 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
1caa0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
1cab0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1cac0 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
1cad0 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
1cae0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1caf0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1cb00 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1cb10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1cb20 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1cb30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cb40 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1cb50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1cb60 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1cb70 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1cb80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1cb90 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1cba0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1cbb0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1cbc0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
1cbd0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1cbe0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
1cbf0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20  Busy Timeout.** 
1cc00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1cc10 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1cc20 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1cc30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1cc40 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1cc50 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1cc60 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1cc70 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1cc80 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1cc90 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1cca0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1ccb0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1ccc0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1ccd0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1cce0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1ccf0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1cd00 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1cd10 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1cd20 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1cd30 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1cd40 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1cd50 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1cd60 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1cd70 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1cd80 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
1cd90 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1cda0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1cdb0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1cdc0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1cdd0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1cde0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1cdf0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1ce00 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1ce10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1ce20 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1ce30 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ce40 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
1ce50 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1ce60 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1ce70 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1ce80 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1ce90 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1cea0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1ceb0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1cec0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1ced0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1cee0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1cef0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1cf00 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1cf10 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45  meout].*/.SQLITE
1cf20 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
1cf30 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1cf40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
1cf50 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
1cf60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cf70 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
1cf80 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
1cf90 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54  g Queries.** MET
1cfa0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1cfb0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1cfc0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1cfd0 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1cfe0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1cff0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1d000 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1d010 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1d020 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1d030 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1d040 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1d050 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1d060 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1d070 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1d080 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d090 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1d0a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1d0b0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1d0c0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1d0d0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1d0e0 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1d0f0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1d100 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1d110 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1d120 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1d130 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1d140 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1d150 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1d160 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1d170 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1d180 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1d190 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1d1a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1d1b0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1d1c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1d1d0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1d1e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1d1f0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1d200 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1d210 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1d220 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1d230 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1d240 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1d250 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1d260 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1d270 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1d280 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1d290 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1d2a0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1d2b0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1d2c0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1d2d0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1d2e0 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1d2f0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1d300 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1d310 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1d320 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1d330 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1d340 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1d350 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1d360 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1d370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1d380 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1d390 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1d3a0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1d3b0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1d3c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1d3d0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1d3e0 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1d3f0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1d400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1d410 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1d420 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1d430 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1d440 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1d450 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1d460 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1d470 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1d480 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1d490 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1d4a0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1d4b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1d4c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d4d0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1d4e0 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1d4f0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1d500 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1d510 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1d520 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1d530 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1d540 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1d550 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1d560 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d570 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1d580 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1d590 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1d5a0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1d5b0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1d5c0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1d5d0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1d5e0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d5f0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1d600 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1d610 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1d620 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1d630 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1d640 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d650 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1d660 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1d670 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1d680 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1d690 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1d6a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d6b0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1d6c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d6d0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1d6e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d6f0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1d700 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1d710 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1d720 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1d730 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1d740 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1d750 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d760 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1d770 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d780 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1d790 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d7a0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1d7b0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1d7c0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1d7d0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1d7e0 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1d7f0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1d800 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1d810 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1d820 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1d830 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1d840 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1d850 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1d860 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1d870 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1d880 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1d890 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1d8a0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1d8b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d8c0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1d8d0 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1d8e0 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1d8f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d900 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1d910 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1d920 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1d930 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1d940 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1d950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1d960 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1d970 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1d980 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1d990 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1d9a0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1d9b0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1d9c0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1d9d0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1d9e0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1d9f0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1da00 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1da10 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1da20 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1da30 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1da40 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1da50 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1da60 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1da70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1da80 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1da90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1daa0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1dab0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1dac0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1dad0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1dae0 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1daf0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1db00 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1db10 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1db20 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1db30 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1db40 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1db50 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1db60 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1db70 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1db80 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1db90 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1dba0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1dbb0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1dbc0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1dbd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1dbe0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1dbf0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1dc00 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  ALL sqlite3_get_
1dc10 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1dc20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1dc30 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1dc40 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1dc50 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1dc60 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1dc70 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1dc80 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1dc90 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1dca0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1dcb0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1dcc0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1dcd0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1dce0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1dcf0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1dd00 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1dd10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1dd20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1dd30 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1dd40 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1dd50 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1dd60 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
1dd70 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
1dd80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66  TDCALL sqlite3_f
1dd90 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1dda0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1ddb0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1ddc0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1ddd0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1dde0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ddf0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1de00 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1de10 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1de20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1de30 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1de40 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1de50 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1de60 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1de70 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1de80 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1de90 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1dea0 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1deb0 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1dec0 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1ded0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1dee0 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1def0 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1df00 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1df10 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1df20 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1df30 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1df40 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1df50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1df60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1df70 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1df80 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1df90 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1dfa0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1dfb0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1dfc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1dfd0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1dfe0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1dff0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1e000 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1e010 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1e020 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1e030 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1e040 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1e050 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1e060 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1e070 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1e080 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1e090 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1e0a0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1e0b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1e0c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1e0d0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1e0e0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1e0f0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1e100 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1e110 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1e120 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1e130 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1e140 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1e150 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1e160 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1e170 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1e180 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1e190 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1e1a0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1e1b0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1e1c0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1e1d0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1e1e0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1e1f0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1e200 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1e210 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1e220 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1e230 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1e240 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1e250 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1e260 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1e270 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1e280 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1e290 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1e2a0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1e2b0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1e2c0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1e2d0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1e2e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1e2f0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1e300 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1e310 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1e320 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1e330 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1e340 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1e350 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1e360 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1e370 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1e380 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1e390 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1e3a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1e3b0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1e3c0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1e3d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e3e0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1e3f0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1e400 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1e410 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1e420 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1e430 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1e440 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1e450 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1e460 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1e470 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1e480 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1e490 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1e4a0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1e4b0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1e4c0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1e4d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1e4e0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1e4f0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1e500 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1e510 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1e520 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1e530 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1e540 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1e550 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1e560 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1e570 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1e580 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1e590 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1e5a0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1e5b0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1e5c0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e5d0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1e5e0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1e5f0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1e600 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1e610 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1e620 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1e630 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1e640 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1e650 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1e660 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1e670 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1e680 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1e690 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1e6a0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1e6b0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1e6c0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1e6d0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1e6e0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1e6f0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1e700 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1e710 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1e720 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1e730 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1e740 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1e750 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1e760 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1e770 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1e780 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1e790 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1e7a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1e7b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1e7c0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1e7d0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1e7e0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1e7f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e800 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1e810 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1e820 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1e830 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1e840 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e850 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1e860 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1e870 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1e880 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1e890 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1e8a0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1e8b0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1e8c0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1e8d0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1e8e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e8f0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1e900 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1e910 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1e920 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1e930 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1e940 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1e950 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1e960 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1e970 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e980 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1e990 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1e9a0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1e9b0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1e9c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e9d0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1e9e0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1e9f0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1ea00 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1ea10 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1ea20 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1ea30 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1ea40 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ea50 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1ea60 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1ea70 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1ea80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ea90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1eaa0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1eab0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1eac0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1ead0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1eae0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1eaf0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1eb00 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1eb10 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1eb20 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1eb30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1eb40 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1eb50 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1eb60 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1eb70 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1eb80 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1eb90 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1eba0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1ebb0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1ebc0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1ebd0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1ebe0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1ebf0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1ec00 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1ec10 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1ec20 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1ec30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1ec40 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1ec50 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ec60 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1ec70 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1ec80 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1ec90 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1eca0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1ecb0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1ecc0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1ecd0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1ece0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1ecf0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ed00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1ed10 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1ed20 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1ed30 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1ed40 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1ed50 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1ed60 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1ed70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1ed80 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1ed90 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1eda0 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1edb0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1edc0 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1edd0 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1ede0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1edf0 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1ee00 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1ee10 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1ee20 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1ee30 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1ee40 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1ee50 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1ee60 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1ee70 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1ee80 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1ee90 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1eea0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1eeb0 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1eec0 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1eed0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1eee0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1eef0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1ef00 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1ef10 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1ef20 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1ef30 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1ef40 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1ef50 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1ef60 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1ef70 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1ef80 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1ef90 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51   string.)^.*/.SQ
1efa0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53  LITE_API char *S
1efb0 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69  QLITE_CDECL sqli
1efc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1efd0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51  t char*,...);.SQ
1efe0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53  LITE_API char *S
1eff0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1f000 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1f010 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1f020 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ist);.SQLITE_API
1f030 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44   char *SQLITE_CD
1f040 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ECL sqlite3_snpr
1f050 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1f060 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1f070 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1f080 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
1f090 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  L sqlite3_vsnpri
1f0a0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1f0b0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1f0c0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1f0d0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1f0e0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1f0f0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1f100 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1f110 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1f120 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1f130 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1f140 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f150 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1f160 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1f170 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1f180 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1f190 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1f1a0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1f1b0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1f1c0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1f1d0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1f1e0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1f1f0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1f200 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1f210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f220 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1f230 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f240 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1f250 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1f260 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1f270 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1f280 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1f290 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f2a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1f2b0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1f2c0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1f2d0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1f2e0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1f2f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1f300 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1f310 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1f320 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1f330 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f340 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1f350 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1f360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1f370 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69  alloc64(N) routi
1f380 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69  ne works just li
1f390 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ke.** sqlite3_ma
1f3a0 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74  lloc(N) except t
1f3b0 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69  hat N is an unsi
1f3c0 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65  gned 64-bit inte
1f3d0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1f3e0 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69  f a signed 32-bi
1f3f0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
1f400 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1f410 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1f420 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1f430 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1f440 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1f450 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1f460 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1f470 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1f480 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1f490 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1f4a0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1f4b0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1f4c0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1f4d0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1f4e0 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1f4f0 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1f500 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1f510 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1f520 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1f530 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1f540 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1f550 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1f560 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1f570 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1f580 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1f590 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1f5a0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1f5b0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1f5c0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1f5d0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1f5e0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1f5f0 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1f600 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1f610 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1f620 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1f630 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1f640 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1f650 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1f660 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1f670 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1f680 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1f690 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  c()..**.** ^The 
1f6a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f6b0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61  X,N) interface a
1f6c0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1f6d0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1f6e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58  ory allocation X
1f6f0 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1f700 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  N bytes..** ^If 
1f710 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
1f720 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1f730 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20  oc(X,N).** is a 
1f740 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1f750 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1f760 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1f770 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1f780 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20  3_malloc(N)..** 
1f790 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ^If the N parame
1f7a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1f7b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a  ealloc(X,N) is z
1f7c0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1f7d0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1f7e0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1f7f0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1f800 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1f810 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69  ree(X)..** ^sqli
1f820 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f830 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1f840 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1f850 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1f860 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1f870 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1f880 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
1f890 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c   memory is avail
1f8a0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1f8b0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1f8c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1f8d0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1f8e0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1f8f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1f900 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1f910 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1f920 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1f930 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1f940 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61  3_realloc(X,N) a
1f950 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1f960 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1f970 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1f980 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1f990 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  turns NULL and N
1f9a0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
1f9b0 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20  en the.** prior 
1f9c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f  allocation is no
1f9d0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1f9e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1f9f0 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72  loc64(X,N) inter
1fa00 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20  faces works the 
1fa10 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
1fa20 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1fa30 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1fa40 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1fa50 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  ed integer inste
1fa60 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69  ad.** of a 32-bi
1fa70 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1fa80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73  ..**.** ^If X is
1fa90 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1faa0 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  tion previously 
1fab0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1fac0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a  lite3_malloc(),.
1fad0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1fae0 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  c64(), sqlite3_r
1faf0 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c  ealloc(), or sql
1fb00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1fb10 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1fb20 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1fb30 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
1fb40 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hat memory alloc
1fb50 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a  ation in bytes..
1fb60 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
1fb70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1fb80 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74  3_msize(X) might
1fb90 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
1fba0 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1fbb0 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64   bytes requested
1fbc0 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f   when X was allo
1fbd0 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73  cated.  ^If X is
1fbe0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1fbf0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1fc00 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1fc10 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69   zero.  If X poi
1fc20 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67  nts to something
1fc30 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20   that is not.** 
1fc40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1fc50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fc60 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69  on, or if it poi
1fc70 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c  nts to a formerl
1fc80 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72  y.** valid memor
1fc90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61  y allocation tha
1fca0 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66  t has now been f
1fcb0 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  reed, then the b
1fcc0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71  ehavior.** of sq
1fcd0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69  lite3_msize(X) i
1fce0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1fcf0 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c  possibly harmful
1fd00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1fd10 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1fd20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fd30 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1fd40 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1fd50 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20  malloc64(), and 
1fd60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1fd70 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  4().** is always
1fd80 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1fd90 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1fda0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1fdb0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1fdc0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1fdd0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1fde0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1fdf0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1fe00 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1fe10 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1fe20 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1fe30 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1fe40 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1fe50 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1fe60 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1fe70 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1fe80 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1fe90 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1fea0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1feb0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1fec0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1fed0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1fee0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1fef0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1ff00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1ff10 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1ff20 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1ff30 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1ff40 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1ff50 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1ff60 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1ff70 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1ff80 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1ff90 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1ffa0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1ffb0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1ffc0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1ffd0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1ffe0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1fff0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
20000 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
20010 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
20020 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
20030 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
20040 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
20050 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
20060 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
20070 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
20080 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
20090 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
200a0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
200b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
200c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
200d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
200e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
200f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20100 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
20110 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
20120 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
20130 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
20140 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
20150 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
20160 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
20170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
20180 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
20190 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
201a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
201b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
201c0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
201d0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
201e0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
201f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
20200 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
20210 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
20220 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
20230 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
20240 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
20250 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
20260 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20270 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
20280 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
20290 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61  DCALL sqlite3_ma
202a0 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
202b0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
202c0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
202d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
202e0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
202f0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
20300 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
20310 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61  CALL sqlite3_rea
20320 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
20330 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53  lite3_uint64);.S
20340 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
20350 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
20360 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
20370 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
20380 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 53 51 4c  lite3_uint64 SQL
20390 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
203a0 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
203b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
203c0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
203d0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
203e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
203f0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
20400 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
20410 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
20420 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
20430 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20440 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
20450 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
20460 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
20470 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
20480 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
20490 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
204a0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
204b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
204c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
204d0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
204e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
204f0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
20500 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
20510 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
20520 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
20530 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
20540 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20550 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
20560 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
20570 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
20580 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20590 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
205a0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
205b0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
205c0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
205d0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
205e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
205f0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
20600 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20610 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
20620 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
20630 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
20640 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
20650 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
20660 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
20670 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
20680 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
20690 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
206a0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
206b0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
206c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
206d0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
206e0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
206f0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
20700 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
20710 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
20720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
20730 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
20740 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
20750 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
20760 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20770 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
20780 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
20790 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
207a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
207b0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
207c0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
207d0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
207e0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
207f0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
20800 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
20810 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65  DCALL sqlite3_me
20820 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
20830 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
20840 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
20850 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
20860 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20870 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
20880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20890 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
208a0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
208b0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
208c0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
208d0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
208e0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
208f0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
20900 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
20910 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
20920 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
20930 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
20940 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
20950 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
20960 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
20970 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
20980 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
20990 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
209a0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
209b0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
209c0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
209d0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
209e0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
209f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
20a00 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
20a10 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
20a20 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
20a30 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
20a40 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
20a50 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
20a60 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
20a70 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72  P..** ^The P par
20a80 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20  ameter can be a 
20a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
20aa0 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
20ab0 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
20ac0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
20ad0 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
20ae0 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
20af0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
20b00 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ne or a NULL poi
20b10 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e  nter for P, then
20b20 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20   the PRNG is.** 
20b30 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
20b40 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
20b50 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
20b60 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a  mness method of.
20b70 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  ** the default [
20b80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
20b90 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
20ba0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
20bb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
20bc0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
20bd0 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e  ore and a.** non
20be0 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65  -NULL P then the
20bf0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
20c00 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
20c10 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
20c20 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
20c30 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
20c40 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
20c50 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
20c60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
20c70 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
20c80 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
20c90 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
20ca0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
20cb0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
20cc0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
20cd0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
20ce0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
20cf0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
20d00 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
20d10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20d20 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
20d30 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
20d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
20d50 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
20d60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
20d70 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
20d80 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20d90 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
20da0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
20db0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
20dc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20dd0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
20de0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
20df0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
20e00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20e10 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
20e20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20e30 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
20e40 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
20e50 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
20e60 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
20e70 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
20e80 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
20e90 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
20ea0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
20eb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
20ec0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
20ed0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
20ee0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
20ef0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
20f00 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
20f10 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
20f20 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
20f30 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
20f40 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
20f50 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
20f60 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
20f70 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
20f80 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
20f90 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
20fa0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
20fb0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
20fc0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
20fd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
20fe0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
20ff0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
21000 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
21010 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21020 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
21030 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
21040 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
21050 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
21060 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
21070 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
21080 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
21090 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
210a0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
210b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
210c0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
210d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
210e0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
210f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
21100 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
21110 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
21120 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
21130 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
21140 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
21150 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
21160 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
21170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21180 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
21190 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
211a0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
211b0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
211c0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
211d0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
211e0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
211f0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
21200 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
21210 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21220 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21230 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
21240 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
21250 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
21260 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21270 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
21280 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
21290 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
212a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
212b0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
212c0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
212d0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
212e0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
212f0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
21300 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
21310 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
21320 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
21330 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
21340 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
21350 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
21360 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
21370 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
21380 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
21390 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
213a0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
213b0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
213c0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
213d0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
213e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
213f0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21400 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
21410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21420 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
21430 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
21440 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
21450 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
21460 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
21470 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
21480 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
21490 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
214a0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
214b0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
214c0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
214d0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
214e0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
214f0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
21500 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
21510 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
21520 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
21530 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
21540 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
21550 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
21560 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
21570 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
21580 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
21590 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
215a0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
215b0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
215c0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
215d0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
215e0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
215f0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
21600 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
21610 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
21620 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
21630 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
21640 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
21650 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
21660 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
21670 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21680 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
21690 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
216a0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
216b0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
216c0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
216d0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
216e0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
216f0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
21700 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
21710 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
21720 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
21730 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
21740 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
21750 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
21760 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
21770 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
21780 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
21790 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
217a0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
217b0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
217c0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
217d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
217e0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
217f0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
21800 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
21810 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
21820 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
21830 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
21840 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
21850 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
21860 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
21870 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
21880 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
21890 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
218a0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
218b0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
218c0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
218d0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
218e0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
218f0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
21900 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
21910 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
21920 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
21930 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
21940 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
21950 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
21960 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
21970 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
21980 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
21990 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
219a0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
219b0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
219c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
219d0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
219e0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
219f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21a00 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
21a10 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
21a20 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
21a30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
21a40 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
21a50 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
21a60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
21a70 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
21a80 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
21a90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21aa0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
21ab0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
21ac0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
21ad0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21ae0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
21af0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
21b00 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
21b10 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
21b20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21b30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
21b40 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
21b50 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
21b60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
21b70 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
21b80 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
21b90 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
21ba0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
21bb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21bc0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
21bd0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
21be0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
21bf0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
21c00 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
21c10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
21c20 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
21c30 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
21c40 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
21c50 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
21c60 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
21c70 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
21c80 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
21c90 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
21ca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
21cb0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
21cc0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
21cd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21ce0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
21cf0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
21d00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
21d10 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
21d20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
21d30 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
21d40 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
21d50 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
21d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21d70 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
21d80 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
21d90 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
21da0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
21db0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
21dc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21dd0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
21de0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
21df0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
21e00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
21e10 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
21e20 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  L sqlite3_set_au
21e30 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
21e40 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
21e50 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
21e60 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
21e70 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
21e80 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
21e90 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
21ea0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
21eb0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21ec0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
21ed0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21ee0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21ef0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
21f00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
21f10 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
21f20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
21f30 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
21f40 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
21f50 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
21f60 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
21f70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
21f80 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
21f90 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
21fa0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
21fb0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
21fc0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
21fd0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
21fe0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
21ff0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
22000 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
22010 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
22020 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
22030 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
22040 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
22050 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
22060 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
22070 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
22080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22090 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
220a0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
220b0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
220c0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
220d0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
220e0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
220f0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
22100 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
22110 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
22120 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
22130 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
22140 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
22150 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
22170 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
22180 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
22190 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
221a0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
221b0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
221c0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
221d0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
221e0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
221f0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
22200 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
22210 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
22220 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
22230 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
22240 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
22250 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
22260 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
22270 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
22280 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
22290 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
222a0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
222b0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
222c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
222d0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
222e0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
222f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
22300 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
22310 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
22320 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
22330 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
22340 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
22350 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
22360 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
22370 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
22380 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
22390 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
223a0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
223b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
223c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
223d0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
223e0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
223f0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
22400 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
22410 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
22420 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22430 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
22440 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
22450 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
22460 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
22470 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
22480 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
22490 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
224a0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
224b0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
224c0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
224d0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
224e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
224f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22500 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
22510 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
22520 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
22530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22540 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22550 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
22560 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22590 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
225a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
225b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
225c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
225d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
225e0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
225f0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22600 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22630 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
22640 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22650 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22680 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
22690 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
226a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
226b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
226c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
226d0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
226e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
226f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22710 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22720 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22730 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22760 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
22770 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
22780 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
22790 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
227a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227b0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
227c0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
227d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
227e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
227f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22800 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
22810 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
22820 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22850 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
22860 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
22870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
228a0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
228b0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
228c0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
228d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
228e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
228f0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
22900 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
22910 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22920 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22940 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
22950 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
22960 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22970 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22990 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
229a0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
229b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
229c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
229e0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
229f0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
22a00 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22a10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22a20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
22a30 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
22a40 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
22a50 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22a60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22a70 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
22a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
22a90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22ac0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
22ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
22ae0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
22af0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
22b00 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
22b10 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
22b20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
22b30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22b40 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b60 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
22b70 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
22b80 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22b90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22bb0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
22bc0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
22bd0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
22be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c00 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
22c10 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
22c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22c30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c50 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
22c60 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
22c70 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
22c80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ca0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
22cb0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
22cc0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
22cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22cf0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
22d00 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
22d10 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
22d20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d40 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
22d50 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
22d60 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
22d70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
22d90 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
22da0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
22db0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22dc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22de0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
22df0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
22e00 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22e10 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22e30 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
22e40 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
22e50 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22e60 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
22e80 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
22e90 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
22ea0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
22eb0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
22ec0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
22ed0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
22ee0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
22ef0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
22f00 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
22f10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
22f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22f30 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
22f40 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
22f50 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
22f60 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
22f70 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22f80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22f90 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
22fa0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
22fb0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
22fc0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
22fd0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
22fe0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22ff0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
23000 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
23010 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
23020 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
23030 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
23040 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
23050 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
23060 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
23070 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
23080 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
23090 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
230a0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
230b0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
230c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
230d0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
230e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
230f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
23100 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
23110 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
23120 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
23130 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
23140 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
23150 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
23160 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
23170 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
23180 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
23190 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
231a0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
231b0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
231c0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
231d0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
231e0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
231f0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
23200 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
23210 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
23220 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
23230 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
23240 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
23250 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
23260 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
23270 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
23280 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
23290 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
232a0 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
232b0 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
232c0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
232d0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
232e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
232f0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
23300 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
23310 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
23320 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
23330 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
23340 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
23350 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
23360 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
23370 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
23380 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
23390 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
233a0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
233b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
233c0 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
233d0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
233e0 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
233f0 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
23400 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
23410 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
23420 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
23430 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
23440 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
23450 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
23460 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
23470 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
23480 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
23490 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
234a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
234b0 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
234c0 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
234d0 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
234e0 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
234f0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
23500 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
23510 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
23520 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
23530 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
23540 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
23550 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
23560 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
23570 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
23580 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
23590 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
235a0 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
235b0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
235c0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
235d0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
235e0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
235f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
23600 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23610 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
23620 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
23630 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
23640 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
23650 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
23660 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23670 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
23680 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
23690 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
236a0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
236b0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
236c0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
236d0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
236e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
236f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
23700 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
23710 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
23720 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
23730 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
23740 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
23750 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
23760 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
23770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23780 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
23790 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
237a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
237b0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
237c0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
237d0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
237e0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
237f0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
23800 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
23810 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
23820 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23830 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
23840 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
23850 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
23860 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
23870 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
23880 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
23890 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
238a0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
238b0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
238c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
238d0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
238e0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
238f0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
23900 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
23910 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
23920 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
23930 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
23940 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
23950 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
23960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23970 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
23980 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23990 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
239a0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
239b0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
239c0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
239d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
239e0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
239f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23a00 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
23a10 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
23a20 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
23a30 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
23a40 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
23a50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
23a60 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
23a70 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
23a80 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
23a90 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
23aa0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
23ab0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
23ac0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
23ad0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
23ae0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
23af0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23b00 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
23b10 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
23b20 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
23b30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
23b40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
23b50 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
23b60 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
23b70 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
23b80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23b90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
23ba0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
23bb0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
23bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
23bd0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
23be0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
23bf0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
23c00 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  **.*/.SQLITE_API
23c10 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
23c20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f  CALL sqlite3_pro
23c30 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
23c40 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
23c50 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
23c60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23c70 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
23c80 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
23c90 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52  ection.** CONSTR
23ca0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
23cb0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
23cc0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
23cd0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
23ce0 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
23cf0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
23d00 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
23d10 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
23d20 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
23d30 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
23d40 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23d50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
23d60 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
23d70 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
23d80 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
23d90 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
23da0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
23db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23dc0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
23dd0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
23de0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
23df0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
23e00 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
23e10 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
23e20 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
23e30 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
23e40 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
23e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
23e60 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
23e70 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
23e80 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
23e90 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
23ea0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23eb0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
23ec0 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
23ed0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
23ee0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
23ef0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
23f00 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
23f10 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
23f20 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
23f30 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
23f40 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
23f50 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
23f60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
23f70 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
23f80 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
23f90 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
23fa0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
23fb0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
23fc0 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
23fd0 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
23fe0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
23ff0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
24000 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
24010 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
24020 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
24030 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
24040 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
24050 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
24060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24070 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
24080 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
24090 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
240a0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
240b0 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
240c0 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
240d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
240e0 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
240f0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
24100 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
24110 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
24120 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
24130 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
24140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24150 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
24160 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
24170 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
24180 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
24190 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
241a0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
241b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
241c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
241d0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
241e0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
241f0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
24200 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
24210 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
24220 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
24230 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
24240 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
24250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
24260 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
24270 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
24280 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24290 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
242a0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
242b0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
242c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
242d0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
242e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
242f0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
24300 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
24310 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
24320 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
24330 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24340 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
24350 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24360 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
24370 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
24380 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24390 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
243a0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
243b0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
243c0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
243d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
243e0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
243f0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
24400 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
24410 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
24420 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
24430 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
24440 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24450 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
24460 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
24470 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
24480 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
24490 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
244a0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
244b0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
244c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
244d0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
244e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
244f0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
24500 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
24510 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
24520 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
24530 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24540 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
24550 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
24560 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
24570 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24580 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
24590 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
245a0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
245b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
245c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
245d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
245e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
245f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
24600 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
24610 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
24620 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
24630 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
24640 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
24650 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24660 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
24670 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
24680 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
24690 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
246a0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
246b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
246c0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
246d0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
246e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
246f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24700 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
24710 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
24720 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
24730 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
24740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24750 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
24760 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
24770 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
24780 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
24790 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
247a0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
247b0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
247c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
247d0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
247e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
247f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
24800 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
24810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24820 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
24830 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
24840 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
24850 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
24860 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
24870 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
24880 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
24890 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
248a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
248b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
248c0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
248d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
248e0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
248f0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
24900 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
24910 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
24920 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
24930 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
24940 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
24950 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
24960 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
24970 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
24980 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
24990 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
249a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
249b0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
249c0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
249d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
249e0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
249f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
24a00 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
24a10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24a20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
24a30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
24a40 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
24a50 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
24a60 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
24a70 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
24a80 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
24a90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
24aa0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
24ab0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
24ac0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
24ad0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
24ae0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
24af0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
24b00 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
24b10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
24b20 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
24b30 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
24b40 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
24b50 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
24b60 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
24b70 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
24b80 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
24b90 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
24ba0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
24bb0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
24bd0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
24be0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
24bf0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
24c00 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
24c10 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
24c20 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
24c30 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
24c40 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
24c50 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
24c60 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
24c70 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
24c80 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
24c90 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
24ca0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
24cb0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
24cc0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
24cd0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
24ce0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
24cf0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
24d00 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
24d10 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
24d20 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
24d30 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
24d40 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
24d50 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
24d60 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
24d70 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
24d80 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
24d90 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
24da0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
24db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24dc0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
24dd0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
24de0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
24df0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
24e00 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
24e10 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
24e20 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
24e30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
24e40 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
24e50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
24e60 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
24e70 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
24e80 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
24e90 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
24ea0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
24eb0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
24ec0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
24ed0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
24ee0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
24ef0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
24f00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
24f10 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
24f20 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
24f30 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
24f40 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
24f50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
24f60 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
24f70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
24f80 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
24f90 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
24fa0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
24fb0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
24fc0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
24fd0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
24fe0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
24ff0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
25000 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
25010 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
25020 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
25030 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
25040 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
25050 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
25060 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
25070 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
25080 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
25090 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
250a0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
250b0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
250c0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
250d0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
250e0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
250f0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
25100 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
25110 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
25120 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
25130 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
25140 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
25150 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
25160 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
25170 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
25180 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
25190 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
251a0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
251b0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
251c0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
251d0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
251e0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
251f0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
25200 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
25210 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
25220 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
25230 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
25240 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
25250 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
25260 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
25270 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
25280 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
25290 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
252a0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
252b0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
252c0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
252d0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
252e0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
252f0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
25300 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
25310 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
25320 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
25330 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
25340 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77  path. .** ^(On w
25350 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
25360 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
25370 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
25380 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
25390 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
253a0 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a  g. "C:").)^.**.*
253b0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
253c0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
253d0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
253e0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
253f0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
25400 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
25410 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
25420 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
25430 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
25440 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
25450 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
25460 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  ]..** SQLite and
25470 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56   its built-in [V
25480 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20  FSes] interpret 
25490 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
254a0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
254b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
254c0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
254d0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
254e0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
254f0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
25500 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
25510 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
25520 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
25530 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
25540 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
25550 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
25560 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
25570 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
25580 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
25590 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
255a0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
255b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
255c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
255d0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
255e0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
255f0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
25600 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
25610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25620 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
25630 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
25640 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
25650 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
25660 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
25670 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
25680 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
25690 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
256a0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
256b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
256c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
256d0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
256e0 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
256f0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
25700 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
25710 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
25720 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
25730 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
25740 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
25750 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
25760 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
25770 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
25780 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
25790 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
257a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
257b0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
257c0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
257d0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
257e0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
257f0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
25800 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
25810 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
25820 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
25830 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
25840 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
25850 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
25860 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
25870 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
25880 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
25890 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
258a0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
258b0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
258c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
258d0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
258e0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
258f0 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
25900 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
25910 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
25920 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
25930 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
25940 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
25950 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
25960 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
25970 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
25980 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
25990 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
259a0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
259b0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
259c0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
259d0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
259e0 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
259f0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
25a00 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
25a10 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
25a20 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
25a30 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
25a40 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
25a50 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
25a60 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
25a70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
25a80 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25a90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25aa0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
25ab0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
25ac0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
25ad0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
25ae0 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
25af0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
25b00 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
25b10 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
25b20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
25b30 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
25b40 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
25b50 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
25b60 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
25b70 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
25b80 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
25b90 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
25ba0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
25bb0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
25bc0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
25bd0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
25be0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
25bf0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
25c00 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
25c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25c20 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
25c30 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
25c40 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
25c50 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
25c60 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
25c70 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
25c80 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
25c90 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
25ca0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
25cb0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
25cc0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
25cd0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
25ce0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
25cf0 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
25d00 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64  ow parameter ind
25d10 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f  icates whether o
25d20 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20  r not the.**    
25d30 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
25d40 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
25d50 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
25d60 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
25d70 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
25d80 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
25d90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
25da0 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  sides..**.**  <l
25db0 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e  i> <b>nolock</b>
25dc0 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61  : ^The nolock pa
25dd0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
25de0 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d  lean query param
25df0 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63  eter.**     whic
25e00 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65  h if set disable
25e10 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69  s file locking i
25e20 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e  n rollback journ
25e30 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a  al modes.  This.
25e40 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c  **     is useful
25e50 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61   for accessing a
25e60 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66   database on a f
25e70 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64  ilesystem that d
25e80 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73  oes not.**     s
25e90 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20  upport locking. 
25ea0 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62   Caution:  Datab
25eb0 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d  ase corruption m
25ec0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74  ight result if t
25ed0 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72  wo.**     or mor
25ee0 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74  e processes writ
25ef0 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  e to the same da
25f00 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f  tabase and any o
25f10 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20  ne of those.**  
25f20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65     processes use
25f30 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a  s nolock=1..**.*
25f40 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74  *  <li> <b>immut
25f50 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69  able</b>: ^The i
25f60 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74  mmutable paramet
25f70 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25f80 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
25f90 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69  ameter that indi
25fa0 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64  cates that the d
25fb0 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
25fc0 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  stored on.**    
25fd0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
25fe0 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62  .  ^When immutab
25ff0 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74  le is set, SQLit
26000 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
26010 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61  he.**     databa
26020 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62  se file cannot b
26030 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  e changed, even 
26040 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74  by a process wit
26050 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20  h higher.**     
26060 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73  privilege, and s
26070 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  o the database i
26080 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e  s opened read-on
26090 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69  ly and all locki
260a0 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68  ng.**     and ch
260b0 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69  ange detection i
260c0 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75  s disabled.  Cau
260d0 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68  tion: Setting th
260e0 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20  e immutable.**  
260f0 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61     property on a
26100 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
26110 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74  hat does in fact
26120 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75   change can resu
26130 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63  lt.**     in inc
26140 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73  orrect query res
26150 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  ults and/or [SQL
26160 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72  ITE_CORRUPT] err
26170 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20  ors..**     See 
26180 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
26190 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a  CAP_IMMUTABLE]..
261a0 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75  **       .** </u
261b0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
261c0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
261d0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
261e0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
261f0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
26200 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
26210 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
26220 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
26230 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
26240 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
26250 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
26260 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
26270 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
26280 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
26290 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
262a0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
262b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
262c0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
262d0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
262e0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
262f0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
26300 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
26310 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
26320 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
26330 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
26340 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
26350 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26360 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
26370 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
26380 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
26390 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
263a0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
263b0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
263c0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
263d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
263e0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
263f0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
26400 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26410 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
26420 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
26430 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26440 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
26450 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
26460 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
26470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26480 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
26490 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
264a0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
264b0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
264c0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
264d0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
264e0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
264f0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
26500 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
26510 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26520 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
26530 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
26540 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
26550 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
26560 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
26570 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26580 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
26590 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
265a0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
265b0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
265c0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
265d0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
265e0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
265f0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
26600 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
26610 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
26620 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
26630 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
26640 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
26650 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26660 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
26670 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
26680 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
26690 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
266a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
266b0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
266c0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
266d0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
266e0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
266f0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
26700 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
26710 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
26720 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
26730 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
26740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26750 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
26760 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74  .db?vfs=unix-dot
26770 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  file <td>.**    
26780 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
26790 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
267a0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
267b0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
267c0 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20  dotfile".**     
267d0 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64       that uses d
267e0 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63  ot-files in plac
267f0 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73  e of posix advis
26800 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20  ory locking..** 
26810 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
26820 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
26830 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
26840 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
26850 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
26860 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
26870 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
26880 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
26890 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
268a0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
268b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
268c0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
268d0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
268e0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
268f0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
26900 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
26910 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26920 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
26930 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
26940 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
26950 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
26960 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
26970 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
26980 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
26990 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
269a0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
269b0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
269c0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
269d0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
269e0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
269f0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
26a00 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
26a10 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
26a20 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
26a30 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
26a40 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
26a50 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
26a60 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
26a70 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
26a80 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
26a90 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
26aa0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
26ab0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
26ac0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
26ad0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
26ae0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
26af0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
26b00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
26b10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
26b20 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
26b30 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
26b40 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
26b50 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
26b60 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
26b70 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
26b80 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
26b90 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
26ba0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
26bb0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
26bc0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
26bd0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
26be0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
26bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26c00 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
26c10 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
26c20 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
26c30 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
26c40 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
26c50 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
26c60 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
26c70 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
26c80 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
26c90 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
26ca0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
26cb0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
26cc0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
26cd0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
26ce0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26cf0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
26d00 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45  ctory].*/.SQLITE
26d10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
26d20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
26d30 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
26d40 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
26d50 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26d60 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
26d70 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
26d80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
26d90 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
26da0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
26db0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
26dc0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
26dd0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
26de0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
26df0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26e00 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
26e10 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
26e20 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
26e30 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
26e40 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
26e50 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
26e60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
26e70 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
26e80 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
26e90 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26ea0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
26eb0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
26ec0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
26ed0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
26ee0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
26ef0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
26f00 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
26f10 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
26f20 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
26f30 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
26f40 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
26f50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26f60 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
26f70 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
26f80 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
26f90 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
26fa0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
26fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
26fc0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
26fd0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
26fe0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
26ff0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
27000 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
27010 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
27020 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
27030 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
27040 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
27050 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
27060 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
27070 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
27080 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
27090 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
270a0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
270b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
270c0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
270d0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
270e0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
270f0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
27100 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
27110 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
27120 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
27130 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
27140 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
27150 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
27160 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
27170 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27180 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
27190 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
271a0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
271b0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
271c0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
271d0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
271e0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
271f0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
27200 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
27210 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
27220 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
27230 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
27240 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27250 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
27260 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
27270 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
27280 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27290 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
272a0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
272b0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
272c0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
272d0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
272e0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
272f0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
27300 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
27310 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
27320 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27330 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
27340 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
27350 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
27360 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
27370 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
27380 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
27390 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
273a0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
273b0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
273c0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
273d0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
273e0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
273f0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
27400 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
27410 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
27420 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
27430 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
27440 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
27450 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
27460 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
27470 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
27480 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
27490 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
274a0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
274b0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
274c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
274d0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
274e0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
274f0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
27500 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
27510 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
27520 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
27530 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
27540 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
27550 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
27560 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
27570 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
27580 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
27590 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
275a0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
275b0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
275c0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
275d0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
275e0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
275f0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
27600 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
27610 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
27620 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
27630 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
27640 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
27650 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
27660 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
27670 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27680 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
27690 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
276a0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
276b0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
276c0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
276d0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
276e0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
276f0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
27700 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
27710 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
27720 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
27730 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27740 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
27750 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
27760 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
27770 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
27780 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27790 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
277a0 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
277b0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
277c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
277d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
277e0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
277f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27800 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
27810 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
27820 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ult);.SQLITE_API
27830 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
27840 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
27850 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27860 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
27870 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
27880 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
27890 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
278a0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
278b0 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
278c0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
278d0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
278e0 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
278f0 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
27900 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
27910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
27920 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
27930 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
27940 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
27950 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
27960 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
27970 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
27980 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
27990 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
279a0 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f  ll..** If the mo
279b0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
279c0 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75  ll was successfu
279d0 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  l,.** then the r
279e0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
279f0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
27a00 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
27a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27a20 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
27a30 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
27a40 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
27a50 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
27a60 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
27a70 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
27a80 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
27a90 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
27aa0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
27ab0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
27ac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
27ad0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
27ae0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
27af0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
27b00 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
27b10 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
27b20 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
27b30 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
27b40 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
27b50 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
27b60 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
27b70 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
27b80 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
27b90 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
27ba0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
27bb0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
27bc0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
27bd0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
27be0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
27bf0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
27c00 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
27c10 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
27c20 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
27c30 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
27c40 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
27c50 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
27c60 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
27c70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
27c80 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
27c90 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
27ca0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
27cb0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
27cc0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
27cd0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
27ce0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
27cf0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
27d00 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
27d10 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
27d20 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
27d30 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
27d40 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
27d50 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
27d60 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
27d70 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
27d80 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
27d90 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
27da0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
27db0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
27dc0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
27dd0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
27de0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
27df0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
27e00 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
27e10 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
27e20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
27e30 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
27e40 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
27e50 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
27e60 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
27e70 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
27e80 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
27e90 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
27ea0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
27eb0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
27ec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27ed0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
27ee0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
27ef0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
27f00 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
27f10 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
27f20 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
27f30 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
27f40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
27f50 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
27f60 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
27f70 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
27f80 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
27f90 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
27fa0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
27fb0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
27fc0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
27fd0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
27fe0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
27ff0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
28000 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
28010 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
28020 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
28030 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
28040 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
28050 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
28060 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54  be set..*/.SQLIT
28070 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28080 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28090 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
280a0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
280b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
280c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74  CALL sqlite3_ext
280d0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
280e0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
280f0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
28100 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
28110 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  L sqlite3_errmsg
28120 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
28130 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
28140 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
28150 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  L sqlite3_errmsg
28160 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
28170 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
28180 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
28190 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73  ALL sqlite3_errs
281a0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
281b0 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
281c0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
281d0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
281e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
281f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
28200 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
28210 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
28220 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
28230 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
28240 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
28250 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
28260 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
28270 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
28280 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
28290 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
282a0 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
282b0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
282c0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
282d0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
282e0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
282f0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
28300 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
28310 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28320 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
28330 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
28340 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
28350 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
28360 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
28370 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
28380 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
28390 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
283a0 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
283b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
283c0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
283d0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
283e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
283f0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
28400 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
28410 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
28420 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28430 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
28440 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
28450 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
28460 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28470 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
28480 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
28490 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
284a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
284b0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
284c0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
284d0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
284e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
284f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
28500 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
28510 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
28520 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
28530 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
28540 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
28550 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
28560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28570 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
28580 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
28590 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
285a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
285b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
285c0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
285d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
285e0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
285f0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
28600 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
28610 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
28620 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
28630 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
28640 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
28650 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
28660 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28670 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
28680 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
28690 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
286a0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
286b0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
286c0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
286d0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
286e0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
286f0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
28700 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
28710 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
28720 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
28730 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28740 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
28750 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
28760 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
28770 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
28780 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
28790 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
287a0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
287b0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
287c0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
287d0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
287e0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
287f0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
28800 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
28810 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
28820 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
28830 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
28840 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
28850 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
28860 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
28870 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
28880 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
28890 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
288a0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
288b0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
288c0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
288d0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
288e0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
288f0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
28900 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
28910 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
28920 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
28930 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
28940 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
28950 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28960 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28970 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
28980 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
28990 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
289a0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
289b0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
289c0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
289d0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
289e0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
289f0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
28a00 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28a10 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
28a20 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
28a30 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
28a40 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
28a50 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
28a60 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
28a70 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
28a80 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
28a90 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
28aa0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
28ab0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
28ac0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
28ad0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
28ae0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
28af0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
28b00 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
28b10 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
28b20 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
28b30 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
28b40 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
28b50 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
28b60 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
28b70 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
28b80 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
28b90 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
28ba0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
28bb0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
28bc0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
28bd0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
28be0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
28bf0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
28c00 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
28c10 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
28c20 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
28c30 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
28c40 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
28c50 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
28c60 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
28c70 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
28c80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
28c90 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
28ca0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
28cb0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
28cc0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
28cd0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
28ce0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
28cf0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
28d00 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
28d10 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
28d20 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
28d30 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
28d40 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
28d50 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
28d60 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
28d70 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
28d80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
28d90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
28da0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
28db0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
28dc0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
28dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
28de0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
28df0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
28e00 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
28e10 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
28e20 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
28e30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
28e40 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
28e50 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
28e60 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
28e70 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
28e80 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
28e90 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
28ea0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
28eb0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
28ec0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
28ed0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
28ee0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
28ef0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
28f00 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
28f10 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
28f20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
28f30 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
28f40 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
28f50 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28f60 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
28f70 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28f80 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
28f90 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
28fa0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
28fb0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
28fc0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
28fd0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
28fe0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
28ff0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
29000 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29010 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
29020 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
29030 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
29040 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
29050 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
29060 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29070 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
29080 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29090 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
290a0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
290b0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
290c0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
290d0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
290e0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
290f0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29100 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
29110 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
29120 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
29130 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
29140 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
29150 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
29160 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
29170 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
29180 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29190 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
291a0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
291b0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
291c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
291d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
291e0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
291f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29200 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
29210 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29220 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29230 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
29240 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
29250 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
29260 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29270 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
29280 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
29290 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
292a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
292b0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
292c0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
292d0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
292e0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
292f0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
29300 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
29310 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
29320 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
29330 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
29340 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
29350 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
29360 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
29370 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
29380 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29390 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
293a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
293b0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
293c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
293d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
293e0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
293f0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
29400 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29410 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
29420 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29430 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
29440 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29450 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
29460 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
29470 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
29480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
29490 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
294a0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
294b0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
294c0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
294d0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
294e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
294f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
29500 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
29510 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
29520 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
29530 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
29540 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29550 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29560 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
29570 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29580 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
29590 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
295a0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
295b0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
295c0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
295d0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
295e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
295f0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
29600 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29610 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
29620 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29630 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
29640 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
29650 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
29660 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29670 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
29680 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
29690 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
296a0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
296b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
296c0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
296d0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
296e0 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
296f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29700 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
29710 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
29720 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
29730 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
29740 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29750 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
29760 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29770 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
29780 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
29790 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
297a0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
297b0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
297c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
297d0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
297e0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
297f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29800 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
29810 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
29820 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29830 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
29840 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
29850 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29860 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
29870 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
29880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29890 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
298a0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
298b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
298c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
298d0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
298e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
298f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29900 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
29910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29920 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
29930 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
29940 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
29950 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29960 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
29970 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
29980 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
29990 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
299a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
299b0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
299c0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
299d0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
299e0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
299f0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
29a00 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
29a10 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
29a20 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
29a30 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
29a40 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
29a50 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
29a60 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
29a70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
29a80 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
29a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29aa0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
29ab0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
29ac0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
29ad0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
29ae0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
29af0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29b00 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
29b10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29b20 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
29b30 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
29b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
29b50 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
29b60 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
29b70 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
29b80 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
29b90 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
29ba0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
29bb0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29bc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
29bd0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
29be0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
29bf0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
29c00 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
29c10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29c20 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
29c30 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
29c40 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
29c50 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
29c60 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
29c70 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
29c80 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
29c90 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
29ca0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
29cb0 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
29cc0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29cd0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
29ce0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
29cf0 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
29d00 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
29d10 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
29d20 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
29d30 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
29d40 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
29d50 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
29d60 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
29d70 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
29d80 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
29d90 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
29da0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
29db0 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
29dc0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29dd0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
29de0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
29df0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
29e00 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
29e10 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
29e20 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
29e30 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
29e40 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
29e50 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
29e60 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
29e70 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
29e80 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
29e90 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
29ea0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
29eb0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
29ec0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
29ed0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
29ee0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
29ef0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
29f00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
29f10 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
29f20 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
29f30 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
29f40 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
29f50 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
29f60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
29f70 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
29f80 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
29f90 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
29fa0 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
29fb0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
29fc0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
29fd0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
29fe0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
29ff0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
2a000 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
2a010 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
2a020 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
2a030 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
2a040 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
2a050 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
2a060 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
2a070 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2a080 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
2a090 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2a0a0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
2a0b0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
2a0c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
2a0d0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
2a0e0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
2a0f0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
2a100 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2a110 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
2a120 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
2a130 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2a140 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a150 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
2a160 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2a170 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
2a180 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
2a190 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
2a1a0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
2a1b0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
2a1c0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
2a1d0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
2a1e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2a1f0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
2a200 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
2a210 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
2a220 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
2a230 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a240 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
2a250 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
2a260 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2a270 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
2a280 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
2a290 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
2a2a0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
2a2b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a2c0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
2a2d0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
2a2e0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
2a2f0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
2a300 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
2a310 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2a320 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
2a330 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
2a340 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
2a350 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
2a360 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
2a370 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2a380 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2a390 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
2a3a0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
2a3b0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
2a3c0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
2a3d0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
2a3e0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
2a3f0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
2a400 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
2a410 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
2a420 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
2a430 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
2a440 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a450 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
2a460 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
2a470 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
2a480 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
2a490 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
2a4a0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
2a4b0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
2a4c0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
2a4d0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
2a4e0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
2a4f0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
2a500 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
2a510 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
2a520 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
2a530 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
2a540 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
2a550 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
2a560 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a570 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
2a580 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
2a590 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
2a5a0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
2a5b0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
2a5c0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
2a5d0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
2a5e0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
2a5f0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
2a600 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
2a610 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
2a620 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
2a630 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
2a640 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
2a650 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
2a660 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
2a670 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
2a680 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2a690 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
2a6a0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
2a6b0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
2a6c0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
2a6d0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
2a6e0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
2a6f0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
2a700 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
2a710 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
2a720 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
2a730 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2a740 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
2a750 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
2a760 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
2a770 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
2a780 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
2a790 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
2a7a0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
2a7b0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
2a7c0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
2a7d0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence 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 69 66 20 74 68 65 20 70 61 72 61  plan if the para
2a800 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
2a810 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
2a820 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
2a830 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
2a840 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2a850 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
2a860 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
2a870 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
2a880 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
2a890 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
2a8a0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
2a8b0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
2a8c0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
2a8d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2a8e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
2a8f0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2a900 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a910 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a920 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a930 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2a940 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a950 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2a960 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2a970 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2a980 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2a990 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a9a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a9b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a9c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a9d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2a9e0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2a9f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2aa00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2aa10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2aa20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2aa30 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2aa40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2aa50 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2aa60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2aa70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2aa80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2aa90 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2aaa0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2aab0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2aac0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2aad0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2aae0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2aaf0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ab00 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ab10 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ab20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ab30 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2ab40 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2ab50 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2ab60 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2ab70 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ab80 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2ab90 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2aba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2abb0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2abc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2abd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2abe0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2abf0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2ac00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ac10 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2ac20 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ac30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ac40 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ac50 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ac60 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ac70 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ac80 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ac90 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2aca0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2acb0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2acc0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2acd0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2ace0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2acf0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2ad00 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2ad10 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
2ad20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ad30 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2ad40 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ad50 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2ad60 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2ad70 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2ad80 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2ad90 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2ada0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2adb0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2adc0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2add0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2ade0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2adf0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2ae00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2ae10 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2ae20 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2ae30 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2ae40 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2ae50 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2ae60 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2ae70 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2ae80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ae90 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2aea0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2aeb0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
2aec0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
2aed0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
2aee0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2aef0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2af00 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
2af10 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
2af20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
2af30 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2af40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2af50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2af60 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  e16_v2()]..*/.SQ
2af70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2af80 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2af90 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  ALL sqlite3_sql(
2afa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2afb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2afc0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2afd0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2afe0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2aff0 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2b000 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2b010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b020 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b030 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2b040 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2b050 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2b060 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2b070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b080 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2b090 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2b0a0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2b0b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2b0c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2b0d0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2b0e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2b0f0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2b100 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2b110 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2b120 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2b130 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2b140 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2b150 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2b160 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2b170 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2b180 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2b190 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2b1a0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2b1b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2b1c0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2b1d0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2b1e0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2b1f0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2b200 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2b210 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2b220 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2b230 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2b240 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2b250 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2b260 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2b270 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2b280 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2b290 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2b2a0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2b2b0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2b2c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2b2d0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2b2e0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2b2f0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2b300 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2b310 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2b320 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2b330 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2b340 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2b350 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2b360 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b370 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2b380 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2b390 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2b3a0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2b3b0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2b3c0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2b3d0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2b3e0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2b3f0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2b400 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2b410 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2b420 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2b430 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2b440 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2b450 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2b460 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2b470 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2b480 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2b490 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2b4a0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2b4b0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2b4c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2b4d0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2b4e0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2b4f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2b500 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2b510 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53  es on disk..*/.S
2b520 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b530 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b540 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2b550 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
2b560 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b570 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2b580 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
2b590 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
2b5a0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
2b5b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b5c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2b5d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2b5e0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
2b5f0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2b600 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
2b610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b620 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
2b630 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
2b640 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
2b650 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b660 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
2b670 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
2b680 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
2b690 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
2b6a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
2b6b0 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
2b6c0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
2b6d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2b6e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2b6f0 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
2b700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b710 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
2b720 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
2b730 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
2b740 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2b750 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
2b760 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
2b770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b780 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
2b790 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b7a0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
2b7b0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
2b7c0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
2b7d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2b7e0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
2b7f0 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
2b800 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
2b810 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
2b820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b830 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
2b840 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
2b850 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2b860 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
2b870 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
2b880 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
2b890 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
2b8a0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
2b8b0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
2b8c0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
2b8d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
2b8e0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
2b8f0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
2b900 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
2b910 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b920 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d  CALL sqlite3_stm
2b930 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
2b940 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2b950 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
2b960 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
2b970 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
2b980 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
2b990 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
2b9a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2b9b0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
2b9c0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2b9d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b9e0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
2b9f0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
2ba00 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
2ba10 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
2ba20 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
2ba30 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
2ba40 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
2ba50 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
2ba60 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
2ba70 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
2ba80 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
2ba90 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
2baa0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2bab0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
2bac0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
2bad0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
2bae0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
2baf0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
2bb00 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
2bb10 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
2bb20 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2bb30 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
2bb40 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
2bb50 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
2bb60 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
2bb70 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
2bb80 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
2bb90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bba0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
2bbb0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
2bbc0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
2bbd0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
2bbe0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
2bbf0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
2bc00 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
2bc10 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68  lite3_value.  Th
2bc20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  e.** [sqlite3_va
2bc30 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72  lue_dup()] inter
2bc40 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2bc50 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20   to construct a 
2bc60 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65  new .** protecte
2bc70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2bc80 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63  from an unprotec
2bc90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bca0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
2bcb0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
2bcc0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
2bcd0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
2bce0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
2bcf0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
2bd00 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
2bd10 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
2bd20 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2bd30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bd40 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
2bd50 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
2bd60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2bd70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
2bd80 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2bd90 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
2bda0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
2bdb0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
2bdc0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
2bdd0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
2bde0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
2bdf0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
2be00 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
2be10 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
2be20 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
2be30 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
2be40 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
2be50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2be60 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
2be70 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
2be80 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
2be90 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2bea0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2beb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2bec0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
2bed0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
2bee0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
2bef0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
2bf00 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
2bf10 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
2bf20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
2bf30 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
2bf40 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
2bf50 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2bf60 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2bf70 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2bf80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2bf90 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
2bfa0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
2bfb0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
2bfc0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2bfd0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
2bfe0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
2bff0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
2c000 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
2c010 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
2c020 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2c030 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
2c040 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
2c050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c060 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2c070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c080 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2c090 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
2c0a0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
2c0b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2c0c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
2c0d0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
2c0e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c0f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c100 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
2c110 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2c120 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
2c130 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2c140 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
2c150 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2c160 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
2c170 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c180 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
2c190 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
2c1a0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
2c1b0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
2c1c0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
2c1d0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2c1e0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
2c1f0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2c200 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
2c210 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
2c220 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
2c230 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
2c240 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
2c250 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
2c260 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
2c270 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
2c280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c290 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2c2a0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
2c2b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2c2c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2c2d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
2c2e0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
2c2f0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
2c300 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2c310 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
2c320 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
2c330 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
2c340 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2c350 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
2c360 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
2c370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2c380 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
2c390 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2c3a0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
2c3b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2c3c0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
2c3d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2c3e0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
2c3f0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
2c400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
2c410 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
2c420 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c430 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
2c440 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2c450 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2c460 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
2c470 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
2c480 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
2c490 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
2c4a0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
2c4b0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d  er binding}.** M
2c4c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c4d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  tmt.**.** ^(In t
2c4e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2c4f0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
2c500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c510 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
2c520 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
2c530 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
2c540 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
2c550 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
2c560 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
2c570 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
2c580 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2c590 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
2c5a0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
2c5b0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
2c5c0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
2c5d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c5e0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
2c5f0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
2c600 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
2c610 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
2c620 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
2c630 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
2c640 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
2c650 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
2c660 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
2c670 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
2c680 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2c690 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
2c6a0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
2c6b0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
2c6c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2c6d0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
2c6e0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
2c6f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2c700 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
2c710 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2c720 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
2c730 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
2c740 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2c750 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2c760 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
2c770 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c780 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
2c790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2c7a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2c7b0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2c7c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
2c7d0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
2c7e0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
2c7f0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2c800 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
2c810 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
2c820 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
2c830 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
2c840 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
2c850 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2c860 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
2c870 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
2c880 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
2c890 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
2c8a0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
2c8b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
2c8c0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
2c8d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
2c8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c8f0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
2c900 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
2c910 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
2c920 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
2c930 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
2c940 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
2c950 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
2c960 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
2c970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
2c980 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
2c990 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
2c9a0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2c9b0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
2c9c0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
2c9d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2c9e0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
2c9f0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
2ca00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
2ca10 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2ca20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ca30 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2ca40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ca50 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
2ca60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2ca70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ca80 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2ca90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
2caa0 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
2cab0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
2cac0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
2cad0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
2cae0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2caf0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2cb00 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2cb10 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2cb20 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2cb30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2cb40 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2cb50 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2cb60 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2cb70 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2cb80 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2cb90 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2cba0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2cbb0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2cbc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2cbd0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2cbe0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2cbf0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2cc00 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2cc10 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2cc20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2cc30 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2cc40 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2cc50 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2cc60 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2cc70 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cc80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2cc90 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2cca0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2ccb0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2ccc0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2ccd0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2cce0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ccf0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2cd00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2cd10 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2cd20 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2cd30 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2cd40 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
2cd50 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
2cd60 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
2cd70 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
2cd80 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
2cd90 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
2cda0 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
2cdb0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
2cdc0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
2cdd0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
2cde0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
2cdf0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
2ce00 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
2ce10 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2ce20 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
2ce30 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
2ce40 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
2ce50 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
2ce60 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
2ce70 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
2ce80 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
2ce90 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
2cea0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
2ceb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2cec0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2ced0 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
2cee0 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
2cef0 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
2cf00 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2cf10 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2cf20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2cf30 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2cf40 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2cf50 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2cf60 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2cf70 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2cf80 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2cf90 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2cfa0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
2cfb0 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
2cfc0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2cfd0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2cfe0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2cff0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2d000 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2d010 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2d020 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2d030 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2d040 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2d050 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2d060 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2d070 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2d080 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2d090 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2d0a0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2d0b0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2d0c0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2d0d0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2d0e0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2d0f0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2d100 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2d110 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2d120 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
2d130 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2d140 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
2d150 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
2d160 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2d170 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
2d180 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2d190 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2d1a0 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
2d1b0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
2d1c0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
2d1d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d1e0 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
2d1f0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2d200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d210 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
2d220 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
2d230 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
2d240 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
2d250 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
2d260 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
2d270 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
2d280 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2d290 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
2d2a0 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
2d2b0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
2d2c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2d2d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2d2e0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2d2f0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2d300 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2d310 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2d320 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2d330 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2d340 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2d350 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2d360 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2d370 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2d380 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2d390 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2d3a0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2d3b0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2d3c0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2d3d0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2d3e0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2d3f0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2d400 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2d410 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2d420 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2d430 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2d440 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2d450 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2d460 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2d470 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2d480 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2d490 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2d4a0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2d4b0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2d4c0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2d4d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d4e0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2d4f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d500 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2d510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d520 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2d530 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2d540 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2d550 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2d560 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2d570 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2d580 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2d590 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2d5a0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2d5b0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2d5c0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2d5d0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2d5e0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2d5f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2d600 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2d610 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2d620 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2d630 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2d640 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2d650 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2d660 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2d670 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2d680 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2d690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2d6a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d6b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2d6c0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2d6d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2d6e0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2d6f0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2d700 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2d710 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2d720 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2d730 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2d740 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2d750 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2d760 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2d770 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2d780 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2d790 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2d7a0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2d7b0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2d7c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2d7d0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2d7e0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2d7f0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2d800 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2d810 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2d820 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2d830 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2d840 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2d850 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d860 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2d870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d880 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2d890 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2d8a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d8b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2d8c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2d8d0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2d8e0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2d8f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2d900 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2d910 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d920 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2d930 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d940 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2d950 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2d960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d970 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2d980 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2d990 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2d9a0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2d9b0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2d9c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2d9d0 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
2d9e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d9f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2da00 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2da10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2da20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2da30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2da40 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2da50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2da60 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2da70 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
2da80 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2da90 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2daa0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2dab0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
2dac0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2dad0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2dae0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2daf0 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2db00 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2db10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2db20 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2db30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2db40 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2db50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2db60 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2db70 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2db80 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2db90 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2dba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2dbb0 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2dbc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2dbd0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2dbe0 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2dbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dc00 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2dc10 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2dc20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54  encoding);.SQLIT
2dc30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2dc40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2dc50 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2dc60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2dc70 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2dc80 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2dc90 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2dca0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2dcb0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2dcc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2dcd0 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt n);.SQLITE_AP
2dce0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2dcf0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2dd00 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c  d_zeroblob64(sql
2dd10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2dd20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
2dd30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dd40 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
2dd50 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d   Parameters.** M
2dd60 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2dd70 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
2dd80 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2dd90 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2dda0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2ddb0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2ddc0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ddd0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2dde0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2ddf0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2de00 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2de10 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2de20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2de30 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2de40 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2de50 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2de60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2de70 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2de80 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2de90 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2dea0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2deb0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2dec0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2ded0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2dee0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2def0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2df00 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2df10 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2df20 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2df30 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2df40 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2df50 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2df60 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2df70 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2df80 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2df90 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2dfa0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2dfb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2dfc0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2dfd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2dfe0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2dff0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2e000 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e010 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e020 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2e030 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2e040 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e050 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2e060 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e070 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2e080 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2e090 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
2e0a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e0b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e0c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e0d0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2e0e0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2e0f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2e100 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2e110 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2e120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2e130 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2e140 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2e150 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2e160 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2e170 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2e180 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2e190 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2e1a0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2e1b0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2e1c0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2e1d0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2e1e0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2e1f0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2e200 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2e210 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2e220 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2e230 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2e240 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2e250 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2e260 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2e270 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2e280 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2e290 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2e2a0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2e2b0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2e2c0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2e2d0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2e2e0 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2e2f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2e300 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2e310 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2e320 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2e330 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2e340 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2e350 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2e360 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2e370 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2e380 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2e390 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2e3a0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2e3b0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2e3c0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2e3d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e3e0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2e3f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e400 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2e410 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e420 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e430 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2e440 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e450 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2e460 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2e470 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e480 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2e490 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2e4a0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2e4b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2e4c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2e4d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2e4e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e4f0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2e500 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2e510 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
2e520 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e530 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2e540 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2e550 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2e560 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2e570 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2e580 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2e590 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2e5a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2e5b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2e5c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e5d0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2e5e0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2e5f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2e600 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2e610 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2e620 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2e630 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2e640 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2e650 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2e660 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2e670 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2e680 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2e690 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2e6a0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2e6b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2e6c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2e6d0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2e6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2e6f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2e700 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2e710 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e720 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
2e730 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2e740 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2e750 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e760 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2e770 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2e780 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2e790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2e7a0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2e7b0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2e7c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2e7d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e7e0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2e7f0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2e800 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2e810 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2e820 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2e830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2e840 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2e850 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2e860 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2e870 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2e880 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2e890 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2e8a0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
2e8b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2e8c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e8d0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2e8e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e8f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e900 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2e910 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2e920 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2e930 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e940 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2e950 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2e960 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2e970 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2e980 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2e990 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2e9a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e9b0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2e9c0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2e9d0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2e9e0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2e9f0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2ea00 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2ea10 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2ea20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2ea30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ea40 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2ea50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2ea60 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2ea70 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2ea80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2ea90 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2eaa0 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2eab0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2eac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ead0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2eae0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2eaf0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2eb00 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2eb10 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2eb20 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2eb30 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2eb40 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2eb50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2eb60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2eb70 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2eb80 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2eb90 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2eba0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2ebb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ebc0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2ebd0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2ebe0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2ebf0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2ec00 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2ec10 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2ec20 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2ec30 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2ec40 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2ec50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2ec60 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2ec70 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2ec80 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2ec90 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2eca0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2ecb0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2ecc0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2ecd0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2ece0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2ecf0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2ed00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ed10 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2ed20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2ed30 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2ed40 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2ed50 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2ed60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2ed70 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2ed80 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2ed90 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2eda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2edb0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2edc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2edd0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2ede0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2edf0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2ee00 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2ee10 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2ee20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2ee30 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2ee40 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2ee50 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2ee60 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2ee70 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2ee80 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2ee90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2eea0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2eeb0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2eec0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2eed0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2eee0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2eef0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2ef00 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2ef10 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2ef20 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2ef30 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2ef40 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2ef50 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2ef60 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2ef70 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2ef80 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
2ef90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2efa0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2efb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2efc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2efd0 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
2efe0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2eff0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2f000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2f010 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f020 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2f030 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2f040 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2f050 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2f060 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f070 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2f080 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2f090 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2f0a0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2f0b0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2f0c0 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2f0d0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2f0e0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2f0f0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2f100 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2f110 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2f120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2f130 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2f140 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2f150 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2f160 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2f170 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2f180 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2f190 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2f1a0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2f1b0 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2f1c0 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2f1d0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2f1e0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2f1f0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2f200 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2f210 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2f220 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2f230 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2f240 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f250 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2f260 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2f270 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f280 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2f290 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2f2a0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2f2b0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2f2c0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2f2d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f2e0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2f2f0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2f300 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2f310 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2f320 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2f330 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2f340 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2f350 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2f360 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2f370 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2f380 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2f390 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2f3a0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2f3b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f3c0 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2f3d0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2f3e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f3f0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2f400 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2f410 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2f420 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2f430 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2f440 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2f450 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2f460 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2f470 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2f480 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2f490 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2f4a0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2f4b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2f4c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2f4d0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2f4e0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2f4f0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2f500 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2f510 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2f520 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2f530 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2f540 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2f550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2f560 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2f570 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2f580 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2f590 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2f5a0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2f5b0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2f5c0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2f5d0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2f5e0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2f5f0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2f600 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2f610 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2f620 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2f630 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2f640 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2f650 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2f660 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2f670 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2f680 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2f690 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2f6a0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2f6b0 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2f6c0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2f6d0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2f6e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2f6f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2f700 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2f710 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2f720 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2f730 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2f740 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2f750 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2f760 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2f770 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2f780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f790 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2f7a0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2f7b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f7c0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2f7d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2f7e0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2f7f0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2f800 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f810 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2f820 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2f830 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2f840 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2f850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f860 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2f870 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2f880 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2f890 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f8a0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
2f8b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2f8c0 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2f8d0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f8e0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2f8f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2f900 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2f910 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2f920 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2f930 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2f940 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2f950 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2f960 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2f970 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2f980 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f990 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2f9a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f9b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f9c0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2f9d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2f9e0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2f9f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2fa00 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2fa10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2fa20 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2fa30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2fa40 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2fa50 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2fa60 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2fa70 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2fa80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa90 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2faa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2fab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fac0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2fad0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2fae0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2faf0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2fb00 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2fb10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2fb20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fb30 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2fb40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2fb50 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2fb60 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2fb70 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2fb80 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2fb90 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2fba0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2fbb0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2fbc0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2fbd0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2fbe0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2fbf0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2fc00 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2fc10 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2fc20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2fc30 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2fc40 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2fc50 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2fc60 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2fc70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2fc80 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2fc90 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2fca0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2fcb0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2fcc0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2fcd0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2fce0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2fcf0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2fd00 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2fd10 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2fd20 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2fd30 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2fd40 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2fd50 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2fd60 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2fd70 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2fd80 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2fd90 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2fda0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2fdb0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2fdc0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2fdd0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2fde0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2fdf0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2fe00 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2fe10 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2fe20 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2fe30 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2fe40 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2fe50 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2fe60 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2fe70 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2fe80 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2fe90 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2fea0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2feb0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2fec0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2fed0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2fee0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2fef0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2ff00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2ff10 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2ff20 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2ff30 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2ff40 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2ff50 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
2ff60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2ff70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2ff80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2ff90 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2ffa0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2ffb0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2ffc0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2ffd0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2ffe0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2fff0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
30000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30010 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
30020 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
30030 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30040 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  mt.**.** After a
30050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30060 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
30070 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
30080 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
30090 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
300a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
300b0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
300c0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
300d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
300e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
300f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
30100 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
30110 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
30120 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
30130 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
30140 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
30150 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
30160 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
30170 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
30180 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
30190 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
301a0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
301b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
301c0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
301d0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
301e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
301f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
30200 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
30210 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30220 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
30230 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30240 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
30250 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
30260 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
30270 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
30280 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
30290 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
302a0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
302b0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
302c0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
302d0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
302e0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
302f0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
30300 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
30310 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
30320 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
30330 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
30340 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
30350 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
30360 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
30370 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
30380 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
30390 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
303a0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
303b0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
303c0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
303d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
303e0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
303f0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
30400 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
30410 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
30420 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
30430 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
30440 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
30450 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
30460 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
30470 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
30480 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
30490 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
304a0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
304b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
304c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
304d0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
304e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
304f0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
30500 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
30510 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
30520 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
30530 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
30540 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
30550 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
30560 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
30570 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
30580 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
30590 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
305a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
305b0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
305c0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
305d0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
305e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
305f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
30600 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
30610 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
30620 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
30630 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30640 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
30650 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
30660 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
30670 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
30680 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
30690 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
306a0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
306b0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
306c0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
306d0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
306e0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
306f0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
30700 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
30710 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
30720 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
30730 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
30740 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
30750 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
30760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
30770 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
30780 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
30790 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
307a0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
307b0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
307c0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
307d0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
307e0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
307f0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
30800 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
30810 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
30820 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
30830 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
30840 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
30850 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
30860 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
30870 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
30880 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
30890 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
308a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
308b0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
308c0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
308d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
308e0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
308f0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
30900 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
30910 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
30920 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
30930 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
30940 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
30950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
30960 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
30970 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
30980 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
30990 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
309a0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
309b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
309c0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
309d0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
309e0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
309f0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
30a00 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
30a10 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
30a20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
30a30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30a40 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
30a50 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
30a60 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
30a70 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
30a80 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
30a90 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
30aa0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
30ab0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
30ac0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
30ad0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
30ae0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
30af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30b00 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
30b10 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
30b20 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
30b30 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
30b40 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
30b50 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
30b60 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
30b70 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
30b80 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
30b90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30ba0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
30bb0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
30bc0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
30bd0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
30be0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
30bf0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
30c00 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
30c10 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
30c20 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
30c30 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
30c40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30c50 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
30c60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30c70 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
30c80 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30c90 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
30ca0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
30cb0 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
30cc0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
30cd0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
30ce0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
30cf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30d00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
30d10 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
30d20 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
30d30 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
30d40 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
30d50 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
30d60 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
30d70 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
30d80 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
30d90 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
30da0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
30db0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
30dc0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
30dd0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
30de0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
30df0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
30e00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
30e10 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
30e20 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
30e30 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
30e40 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
30e50 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
30e60 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
30e70 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
30e80 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
30e90 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
30ea0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
30eb0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
30ec0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
30ed0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
30ee0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
30ef0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
30f00 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
30f10 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
30f20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30f30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
30f40 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
30f50 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
30f60 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
30f70 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
30f80 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
30f90 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
30fa0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
30fb0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
30fc0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
30fd0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
30fe0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
30ff0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
31000 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
31010 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
31020 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
31030 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
31040 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
31050 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
31060 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
31070 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
31080 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
31090 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
310a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
310b0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
310c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
310d0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
310e0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
310f0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
31100 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
31110 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
31120 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
31130 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
31140 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
31150 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31160 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74  DCALL sqlite3_st
31170 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
31180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31190 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
311a0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
311b0 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
311c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
311d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
311e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
311f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31200 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
31210 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
31220 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
31230 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
31240 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
31250 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
31260 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
31270 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
31280 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
31290 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
312a0 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
312b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
312c0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
312d0 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
312e0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
312f0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
31300 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
31310 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
31320 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
31330 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
31340 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
31350 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
31360 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31370 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
31380 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
31390 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
313a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
313b0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
313c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
313d0 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
313e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
313f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
31400 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
31410 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
31420 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
31430 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
31440 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
31450 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
31460 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
31470 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
31480 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
31490 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
314a0 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
314b0 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
314c0 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
314d0 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
314e0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
314f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
31500 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
31510 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
31520 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
31530 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
31540 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
31550 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
31560 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
31570 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
31580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
31590 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
315a0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
315b0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
315c0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
315d0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
315e0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
315f0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
31600 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
31610 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
31620 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
31630 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
31640 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
31650 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
31660 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
31670 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
31680 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
31690 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
316a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
316b0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
316c0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
316d0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
316e0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
316f0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
31700 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
31710 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
31720 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
31730 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
31740 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
31750 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
31760 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
31770 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
31780 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
31790 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
317a0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
317b0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
317c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
317d0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
317e0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
317f0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
31800 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
31810 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
31820 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
31830 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
31840 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
31850 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
31860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31870 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
31880 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
31890 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
318a0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
318b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
318c0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
318d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
318e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
318f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
31900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
31910 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
31920 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
31930 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
31940 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
31950 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
31960 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
31970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31980 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
31990 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
319a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
319b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
319c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
319d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
319e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
319f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
31a00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
31a10 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
31a20 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
31a30 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
31a40 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
31a50 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
31a60 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
31a70 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
31a80 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
31a90 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
31aa0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
31ab0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
31ac0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
31ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
31ae0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
31af0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
31b00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
31b10 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
31b20 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
31b30 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
31b40 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
31b50 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
31b60 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
31b70 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
31b80 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
31b90 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
31ba0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
31bb0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
31bc0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
31bd0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31be0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
31bf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
31c00 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
31c10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31c20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
31c30 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
31c40 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
31c50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
31c60 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
31c70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
31c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
31c90 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
31ca0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
31cb0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
31cc0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
31cd0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
31ce0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
31cf0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
31d00 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
31d10 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
31d20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
31d30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31d40 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
31d50 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
31d60 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
31d70 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
31d80 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
31d90 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
31da0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
31db0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31dc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31dd0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
31de0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
31df0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
31e00 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
31e10 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
31e20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
31e30 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
31e40 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
31e50 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
31e60 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
31e70 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
31e80 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
31e90 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
31ea0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
31eb0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
31ec0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
31ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31ee0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
31ef0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
31f00 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
31f10 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
31f20 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
31f30 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
31f40 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
31f50 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
31f60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
31f70 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
31f80 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
31f90 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
31fa0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
31fb0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
31fc0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
31fd0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
31fe0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
31ff0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
32000 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32010 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
32020 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
32030 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
32040 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
32050 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
32060 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32070 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
32080 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
32090 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
320a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
320b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
320c0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
320d0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
320e0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
320f0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
32100 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32110 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32120 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
32130 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
32140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32150 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
32160 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
32170 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
32180 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
32190 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
321a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
321b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
321c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
321d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
321e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
321f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32200 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
32210 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
32220 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
32230 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
32240 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
32250 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32260 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
32270 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
32280 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
32290 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
322a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
322b0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
322c0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
322d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
322e0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
322f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
32300 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
32310 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32320 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
32330 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
32340 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
32350 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
32360 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
32370 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
32380 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
32390 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
323a0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
323b0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
323c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
323d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
323e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
323f0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
32400 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
32410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
32420 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
32430 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
32440 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
32450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32460 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
32470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32480 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
32490 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
324a0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
324b0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
324c0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
324d0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
324e0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
324f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
32500 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
32510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32520 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
32530 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
32540 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
32550 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
32560 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
32570 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
32580 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
32590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
325a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
325b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
325c0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
325d0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
325e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
325f0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
32600 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
32610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
32620 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
32630 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
32640 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
32650 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c  .** <b>Warning:<
32660 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  /b> ^The object 
32670 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
32680 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
32690 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
326a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
326b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
326c0 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72  .  In a multithr
326d0 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e  eaded environmen
326e0 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65  t,.** an unprote
326f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32700 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e  ue object may on
32710 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c  ly be used safel
32720 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  y with.** [sqlit
32730 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
32740 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
32750 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
32760 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
32770 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32780 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
32790 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
327a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
327b0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
327c0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
327d0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
327e0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
327f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32800 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
32810 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
32820 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32830 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
32840 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
32850 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a  not threadsafe..
32860 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32870 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
32880 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32890 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
328a0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
328b0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
328c0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
328d0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
328e0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
328f0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
32900 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
32910 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
32920 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
32930 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
32940 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
32950 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
32960 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
32970 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
32980 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
32990 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
329a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
329b0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
329c0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
329d0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
329e0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
329f0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
32a00 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
32a10 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32a20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
32a30 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
32a40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
32a50 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
32a60 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
32a70 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
32a80 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
32a90 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
32aa0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
32ab0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
32ac0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32ad0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
32ae0 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
32af0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
32b00 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
32b10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32b20 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
32b30 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
32b40 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
32b50 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
32b60 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
32b70 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
32b80 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
32b90 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
32ba0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32bb0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
32bc0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
32bd0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
32be0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
32bf0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
32c00 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
32c10 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
32c20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
32c30 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
32c40 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
32c50 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
32c60 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32c70 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
32c80 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
32c90 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
32ca0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
32cb0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
32cc0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32cd0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
32ce0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32cf0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
32d00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
32d10 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
32d20 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
32d30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
32d40 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
32d50 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
32d60 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
32d70 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
32d80 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
32d90 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
32da0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
32db0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
32dc0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
32dd0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
32de0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
32df0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
32e00 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
32e10 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
32e20 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
32e30 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
32e40 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
32e50 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
32e60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
32e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32e80 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
32e90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32ea0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
32eb0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
32ec0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
32ed0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
32ee0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
32ef0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
32f00 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
32f10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
32f20 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
32f30 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
32f40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32f50 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
32f60 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
32f70 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
32f80 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
32f90 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
32fa0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
32fb0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
32fc0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
32fd0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
32fe0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
32ff0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
33000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33010 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
33020 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33030 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
33040 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
33050 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
33060 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
33070 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
33080 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
33090 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
330a0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
330b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
330c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
330d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
330e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
330f0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
33100 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
33110 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
33120 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
33130 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
33140 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
33150 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
33160 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
33170 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
33180 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
33190 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
331a0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
331b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
331c0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
331d0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
331e0 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
331f0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
33200 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
33210 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
33220 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
33230 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
33240 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
33250 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
33260 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
33270 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
33280 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
33290 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
332a0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
332b0 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
332c0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
332d0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
332e0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
332f0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
33300 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
33310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33320 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
33330 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
33340 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
33350 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
33360 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
33370 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
33380 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
33390 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
333a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
333b0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
333c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
333d0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
333e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
333f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
33400 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
33410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33420 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
33430 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
33440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33450 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
33460 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
33470 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
33480 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
33490 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
334a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
334b0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
334c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
334d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
334e0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
334f0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
33500 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
33510 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
33520 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
33530 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
33540 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
33550 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33560 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
33570 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
33580 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33590 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
335a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
335b0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
335c0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
335d0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
335e0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
335f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
33600 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
33610 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
33620 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
33630 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
33640 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
33650 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33660 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
33670 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
33680 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
33690 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
336a0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
336b0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
336c0 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73  em>not</em> pass
336d0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
336e0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
336f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33700 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
33710 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
33720 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
33730 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
33740 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
33750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
33760 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
33770 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
33780 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
33790 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
337a0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
337b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
337c0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
337d0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
337e0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
337f0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
33800 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
33810 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
33820 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
33830 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
33840 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
33850 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
33860 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
33870 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
33880 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
33890 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
338a0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
338b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
338c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
338d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
338e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
338f0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
33900 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33910 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
33920 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33940 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
33950 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
33960 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53  ITE_API double S
33970 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33990 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
339a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
339b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
339c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
339d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
339e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
339f0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33a00 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
33a10 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
33a20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33a30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
33a40 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
33a50 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
33a60 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
33a70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33a80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33a90 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
33aa0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
33ab0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
33ac0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
33ad0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33ae0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
33af0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33b00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33b10 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33b30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
33b40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
33b50 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
33b60 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f  3_value *SQLITE_
33b70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33b80 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
33b90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33ba0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
33bb0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
33bc0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
33bd0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
33be0 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
33bf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
33c00 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
33c10 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
33c20 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
33c30 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
33c40 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
33c50 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33c60 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
33c70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
33c80 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
33c90 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
33ca0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
33cb0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
33cc0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
33cd0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
33ce0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
33cf0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
33d00 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
33d10 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
33d20 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
33d30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
33d40 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
33d50 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
33d60 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
33d70 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
33d80 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
33d90 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
33da0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
33db0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
33dc0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
33dd0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
33de0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
33df0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
33e00 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
33e10 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
33e20 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
33e30 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
33e40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
33e50 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
33e60 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
33e70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
33e80 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
33e90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
33ea0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
33eb0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
33ec0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
33ed0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
33ee0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
33ef0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
33f00 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
33f10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
33f20 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
33f30 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
33f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33f50 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
33f60 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
33f70 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
33f80 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
33f90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33fa0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
33fb0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
33fc0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
33fd0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
33fe0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
33ff0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
34000 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
34010 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
34020 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
34030 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
34040 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
34050 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
34060 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
34070 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
34080 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34090 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
340a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
340b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
340c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
340d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
340e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
340f0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54  nt Object.** MET
34100 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
34110 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
34120 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
34130 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
34140 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
34150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
34160 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
34170 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
34180 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
34190 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
341a0 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
341b0 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
341c0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
341d0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
341e0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
341f0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
34200 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
34210 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
34220 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
34230 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
34240 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
34250 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
34260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
34270 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
34280 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
34290 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
342a0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
342b0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
342c0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
342d0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
342e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
342f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
34300 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
34310 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
34320 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
34330 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
34340 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
34350 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
34360 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
34370 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
34380 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
34390 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
343a0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
343b0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
343c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
343d0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
343e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
343f0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
34400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34410 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
34420 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
34430 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
34440 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
34450 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
34460 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
34470 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
34480 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
34490 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
344a0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
344b0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
344c0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
344d0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
344e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
344f0 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
34500 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34510 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65  ALL sqlite3_rese
34520 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
34530 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
34540 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
34550 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
34560 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
34570 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
34580 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34590 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
345a0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
345b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
345c0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
345d0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
345e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
345f0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
34600 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
34610 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
34620 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
34630 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
34640 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34650 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
34660 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
34670 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34680 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34690 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
346a0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
346b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
346c0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
346d0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
346e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
346f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
34700 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
34710 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
34720 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34730 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
34740 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34750 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
34760 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
34770 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
34780 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
34790 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
347a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
347b0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
347c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
347d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
347e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
347f0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
34800 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
34810 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
34820 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
34830 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
34840 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
34850 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
34860 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
34870 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34880 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
34890 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
348a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
348b0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
348c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
348d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
348e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
348f0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
34900 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
34910 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
34920 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
34930 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
34940 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
34950 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
34960 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
34970 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
34980 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
34990 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
349a0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
349b0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
349c0 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
349d0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
349e0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
349f0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
34a00 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
34a10 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
34a20 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
34a30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
34a40 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
34a50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
34a60 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
34a70 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
34a80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
34a90 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
34aa0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
34ab0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
34ac0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
34ad0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
34ae0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34af0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
34b00 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
34b10 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
34b20 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
34b30 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
34b40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
34b50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
34b60 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
34b70 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
34b80 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
34b90 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
34ba0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
34bb0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
34bc0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
34bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
34be0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
34bf0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
34c00 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
34c10 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
34c20 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
34c30 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
34c40 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
34c50 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
34c60 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
34c70 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
34c80 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
34c90 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
34ca0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34cb0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
34cc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
34cd0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
34ce0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
34cf0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34d00 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
34d10 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
34d20 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
34d30 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
34d40 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
34d50 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
34d60 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
34d70 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
34d80 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
34d90 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
34da0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
34db0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
34dc0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
34dd0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
34de0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
34df0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
34e00 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
34e10 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
34e20 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
34e30 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
34e40 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
34e50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34e60 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
34e70 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
34e80 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
34e90 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
34ea0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
34eb0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
34ec0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
34ed0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
34ee0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
34ef0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
34f00 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
34f10 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
34f20 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
34f30 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
34f40 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
34f50 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
34f60 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
34f70 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
34f80 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
34f90 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
34fa0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
34fb0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
34fc0 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
34fd0 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
34fe0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
34ff0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
35000 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
35010 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
35020 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
35030 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
35040 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
35050 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
35060 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
35070 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
35080 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
35090 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
350a0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
350b0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
350c0 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
350d0 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
350e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
350f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
35100 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
35110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35120 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
35130 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
35140 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
35150 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
35160 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
35170 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
35180 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
35190 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
351a0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
351b0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
351c0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
351d0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
351e0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
351f0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
35200 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
35210 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
35220 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
35230 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
35240 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
35250 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
35260 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
35270 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
35280 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
35290 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
352a0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
352b0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
352c0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
352d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
352e0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
352f0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
35300 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
35310 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
35320 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
35330 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
35340 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
35350 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
35360 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
35370 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
35380 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
35390 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
353a0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
353b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
353c0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
353d0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
353e0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
353f0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
35400 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
35410 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
35420 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
35430 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
35440 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
35450 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
35460 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
35470 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
35480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35490 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
354a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
354b0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
354c0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
354d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
354e0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
354f0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
35500 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
35510 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
35520 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
35530 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
35540 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
35550 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
35560 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35570 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35580 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35590 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
355a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
355b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
355c0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
355d0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
355e0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
355f0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
35600 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
35610 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
35620 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
35630 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
35640 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
35650 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
35660 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
35670 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
35680 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35690 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
356a0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
356b0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
356c0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
356d0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
356e0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
356f0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
35700 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35710 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
35720 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
35730 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
35740 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
35750 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35760 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35770 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
35780 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
35790 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
357a0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
357b0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
357c0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
357d0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
357e0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
357f0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
35800 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
35810 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
35820 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
35830 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
35840 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35850 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
35860 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
35870 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
35880 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35890 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
358a0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
358b0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
358c0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
358d0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
358e0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
358f0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
35900 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35910 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
35920 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
35930 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35940 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
35950 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
35960 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
35970 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35980 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
35990 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
359a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
359b0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
359c0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
359d0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
359e0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
359f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
35a00 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
35a10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
35a20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35a30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35a40 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
35a50 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35a60 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
35a70 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35a80 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35a90 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35aa0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35ab0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35ac0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35ad0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
35ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35af0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35b00 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35b10 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
35b20 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
35b30 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
35b40 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
35b50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35b60 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
35b70 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
35b80 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
35b90 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
35ba0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
35bb0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
35bc0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
35bd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35be0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35bf0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
35c00 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
35c10 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
35c20 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
35c30 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
35c40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
35c50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
35c60 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
35c70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35c80 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
35c90 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
35ca0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
35cb0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
35cc0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
35cd0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
35ce0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
35cf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35d00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35d10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35d20 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
35d30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35d40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35d50 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
35d60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35d70 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
35d80 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
35d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
35da0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
35db0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
35dc0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
35dd0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
35de0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
35df0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
35e00 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
35e10 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
35e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
35e30 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
35e40 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
35e50 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
35e60 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
35e70 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
35e80 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
35e90 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
35ea0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
35eb0 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
35ec0 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
35ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35ee0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
35ef0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
35f00 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
35f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
35f20 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
35f30 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
35f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35f50 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
35f60 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
35f70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35f80 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
35f90 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
35fa0 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
35fb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
35fc0 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
35fd0 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
35fe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
35ff0 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
36000 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
36010 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
36020 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
36030 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36040 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
36050 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
36060 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
36070 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36080 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
36090 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
360a0 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
360b0 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
360c0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
360d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
360e0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
360f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
36100 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
36110 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
36120 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
36130 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
36140 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
36150 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
36160 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
36170 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
36180 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
36190 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
361a0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
361b0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
361c0 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72  ions.  To encour
361d0 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  age programmers 
361e0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73  to avoid.** thes
361f0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
36200 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e  will not explain
36210 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
36220 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
36230 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
36240 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
36250 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36260 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36270 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
36280 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
36290 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
362a0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
362b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
362c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
362d0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
362e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
362f0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
36300 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
36310 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36320 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
36330 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
36340 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
36350 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
36360 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
36370 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
36380 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f  CALL sqlite3_glo
36390 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
363a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
363b0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
363c0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
363d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65  ALL sqlite3_thre
363e0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
363f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
36400 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
36410 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
36420 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
36430 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
36440 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
36450 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
36460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
36470 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
36480 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
36490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
364a0 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 65  aining SQL Value
364b0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
364c0 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
364d0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
364e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
364f0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
36500 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
36510 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
36520 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
36530 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
36540 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
36550 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
36560 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
36570 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  gate.  .**.** Th
36580 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
36590 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
365a0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
365b0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
365c0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
365d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
365e0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
365f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36600 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
36610 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
36620 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
36630 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
36640 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
36650 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
36660 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
36670 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
36680 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
36690 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
366a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
366b0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
366c0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
366d0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
366e0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
366f0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
36700 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
36710 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
36720 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
36730 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
36740 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36750 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
36760 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
36770 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
36780 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36790 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
367a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
367b0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
367c0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
367d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
367e0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
367f0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
36800 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
36810 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
36820 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
36830 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
36840 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
36850 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
36860 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
36870 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
36880 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
36890 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
368a0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
368b0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
368c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
368d0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
368e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
368f0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
36900 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
36910 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
36920 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
36930 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
36940 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
36950 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
36960 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
36970 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
36980 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
36990 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
369a0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
369b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
369c0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
369d0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
369e0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
369f0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
36a00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
36a10 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
36a20 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
36a30 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
36a40 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
36a50 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
36a60 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
36a70 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
36a80 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
36a90 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
36aa0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
36ab0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
36ac0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
36ad0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
36ae0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
36af0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
36b00 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
36b10 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
36b20 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
36b30 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
36b40 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
36b50 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
36b60 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
36b70 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
36b80 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36b90 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
36ba0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
36bb0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
36bc0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
36bd0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
36be0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
36bf0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
36c00 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
36c10 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
36c20 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
36c30 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
36c40 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
36c50 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
36c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
36c70 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
36c80 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
36c90 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
36ca0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
36cb0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
36cc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36cd0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
36ce0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
36cf0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
36d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
36d10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
36d20 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
36d30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
36d40 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
36d50 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
36d60 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
36d70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36d80 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
36d90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36da0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
36db0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36dc0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
36dd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
36de0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
36df0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36e00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36e10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36e20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36e30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
36e50 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
36e60 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36e70 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f  I double SQLITE_
36e80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36e90 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
36ea0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36eb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
36ec0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36ed0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
36ee0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
36ef0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
36f00 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  3_int64 SQLITE_S
36f10 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
36f20 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
36f30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36f40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
36f50 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49  igned char *SQLI
36f60 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36f70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
36f80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
36f90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
36fa0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
36fb0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36fc0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
36fd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36fe0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
36ff0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
37000 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
37010 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
37020 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
37030 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
37040 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
37050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37060 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
37070 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37080 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
37090 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
370a0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
370b0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
370c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
370d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
370e0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
370f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
37100 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37110 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20  EF: Finding The 
37120 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56  Subtype Of SQL V
37130 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
37140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
37150 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
37160 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56  _value_subtype(V
37170 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
37180 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66  ns the subtype f
37190 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63  or.** an [applic
371a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
371b0 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75  L function] argu
371c0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62  ment V.  The sub
371d0 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  type.** informat
371e0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
371f0 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65  to pass a limite
37200 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  d amount of cont
37210 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  ext from.** one 
37220 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
37230 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68  another.  Use th
37240 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
37250 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20  t_subtype()].** 
37260 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74  routine to set t
37270 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74  he subtype for t
37280 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37290 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  of an SQL functi
372a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
372b0 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66   makes no use of
372c0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e   subtype itself.
372d0 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73    It merely pass
372e0 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a  es the subtype.*
372f0 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c  * from the resul
37300 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63  t of one [applic
37310 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
37320 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f  L function] into
37330 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66   the.** input of
37340 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c   another..*/.SQL
37350 49 54 45 5f 41 50 49 20 75 6e 73 69 67 6e 65 64  ITE_API unsigned
37360 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
37370 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37380 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  e_subtype(sqlite
37390 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
373a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79  * CAPI3REF: Copy
373b0 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61   And Free SQL Va
373c0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
373d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
373e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
373f0 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
37400 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
37410 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
37420 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
37430 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75  bject D and retu
37440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
37450 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68   that copy.  ^Th
37460 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37470 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  ] returned.** is
37480 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
37490 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
374a0 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20  ect even if the 
374b0 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a  input is not..**
374c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
374d0 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
374e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
374f0 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f  L if V is NULL o
37500 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79  r if a.** memory
37510 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37520 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
37530 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
37540 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72  (V) interface fr
37550 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ees an [sqlite3_
37560 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
37570 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
37580 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
37590 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
375a0 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c    ^If V is a NUL
375b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  L pointer.** the
375c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  n sqlite3_value_
375d0 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72  free(V) is a har
375e0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
375f0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
37600 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45  e3_value *SQLITE
37610 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
37620 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74  _value_dup(const
37630 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
37640 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37650 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
37660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
37670 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
37680 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
37690 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
376a0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
376b0 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
376c0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
376d0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
376e0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
376f0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
37700 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
37710 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
37720 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
37730 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
37740 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
37750 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
37760 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37770 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
37780 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
37790 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
377a0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
377b0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
377c0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
377d0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
377e0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
377f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37800 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
37810 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
37820 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
37830 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
37840 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
37850 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
37860 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
37870 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37880 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
37890 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
378a0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
378b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
378c0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
378d0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
378e0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
378f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
37900 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
37910 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
37920 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
37930 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
37940 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
37950 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
37960 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
37970 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
37980 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
37990 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
379a0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
379b0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
379c0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
379d0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
379e0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
379f0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
37a00 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37a10 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
37a20 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
37a30 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
37a40 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
37a50 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
37a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
37a70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37a80 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
37a90 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
37aa0 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
37ab0 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
37ac0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
37ad0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
37ae0 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
37af0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
37b00 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
37b10 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
37b20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
37b30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37b40 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
37b50 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
37b60 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
37b70 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
37b80 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
37b90 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
37ba0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
37bb0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
37bc0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37bd0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
37be0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
37bf0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37c00 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
37c10 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
37c20 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
37c30 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
37c40 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
37c50 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
37c60 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
37c70 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
37c80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37c90 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
37ca0 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
37cb0 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
37cc0 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
37cd0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
37ce0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
37cf0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
37d00 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
37d10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37d20 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
37d30 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
37d40 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
37d50 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
37d60 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
37d70 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
37d80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
37d90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
37da0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
37db0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37dc0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
37dd0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
37de0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
37df0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
37e00 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
37e10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
37e20 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
37e30 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
37e40 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
37e50 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
37e60 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
37e70 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
37e80 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
37e90 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
37ea0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67  DCALL sqlite3_ag
37eb0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37ec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37ed0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
37ee0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37ef0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
37f00 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
37f10 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
37f20 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
37f30 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
37f40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37f50 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
37f60 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
37f70 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
37f80 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
37f90 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
37fa0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
37fb0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37fc0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
37fd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37fe0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
37ff0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
38000 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
38010 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
38020 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
38030 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
38040 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
38050 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
38060 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
38070 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
38080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38090 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
380a0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
380b0 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
380c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
380d0 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
380e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
380f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38100 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
38110 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
38120 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38130 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
38140 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
38150 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
38160 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
38170 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
38180 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
38190 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
381a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
381b0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
381c0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
381d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
381e0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
381f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
38200 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
38210 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
38220 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
38230 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38240 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
38250 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
38260 20 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 45   sqlite3 *SQLITE
38270 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38280 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
38290 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
382a0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
382b0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
382c0 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
382d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
382e0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
382f0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
38300 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28  may be used by (
38310 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53  non-aggregate) S
38320 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
38330 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
38340 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
38350 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
38360 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
38370 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
38380 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
38390 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
383a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
383b0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
383c0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
383d0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
383e0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
383f0 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
38400 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78  reserved.  An ex
38410 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72  ample.** of wher
38420 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20  e this might be 
38430 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72  useful is in a r
38440 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
38450 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75  n matching.** fu
38460 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
38470 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
38480 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
38490 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74  ession can be st
384a0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
384b0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
384c0 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20  ith the pattern 
384d0 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65  string.  .** The
384e0 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  n as long as the
384f0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20   pattern string 
38500 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65  remains the same
38510 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65  ,.** the compile
38520 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
38530 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
38540 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
38550 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
38560 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
38570 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
38580 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
38590 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
385a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
385b0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
385c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
385d0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
385e0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
385f0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
38600 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
38610 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
38620 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38630 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65  unction. ^If the
38640 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
38650 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
38660 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f  with the functio
38670 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73  n argument, this
38680 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
38690 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
386a0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55  .** returns a NU
386b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
386c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
386d0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
386e0 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  ,X) interface sa
386f0 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74  ves P as metadat
38700 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
38710 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
38720 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
38730 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
38740 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20   ^Subsequent.** 
38750 63 61 6c