System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ad395d45e2c977ba3d7ecc4006ba54d3564b39b9:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 38 2e 31 32 2e 20 20  ersion 3.8.12.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d  e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72  ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56   options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c  C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20  d be done first 
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76  uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20  ent spurious.** 
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75  s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74  ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68  his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74  er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79   are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f   this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e  nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68  egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72  *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73  s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e  pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56  .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53  C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e  VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72  ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72  able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72  able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72  able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72  able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72  able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72  able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72  able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72  able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72  able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72  able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72  able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72  able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72  able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72  able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e  able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f  dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e  MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20  dif /* _MSVC_H_ 
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e  *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77  *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66  here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   in sqliteInt.h 
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57  al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65  vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a  le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54  15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57  is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f  ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64  ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e  efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56  EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20  xWorks.  Set up 
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79  things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a   for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b  #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70  s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d  thread.h>  /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63  algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ache */.#define 
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65  OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f  fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53  THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f  QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20  RECURSIVE_MUTEX 
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e  _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53  SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43  QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65  KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20  fine HAVE_UTIME 
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20  1.#else./* This 
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20  is not VxWorks. 
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f  WORKS 0.#endif /
11f0: 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b  * defined(_WRS_K
1200: 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a  ERNEL) */../****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f  ********** End o
1220: 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  f vxworks.h ****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69  ********** Conti
1270: 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c  nuing where we l
1280: 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74  eft off in sqlit
1290: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a  *********/../*.*
12b0: 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73  * These #defines
12c0: 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e   should enable >
12d0: 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74  2GB file support
12e0: 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65   on POSIX if the
12f0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  .** underlying o
1300: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1310: 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66  supports it.  If
1320: 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a   the OS lacks.**
1330: 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70   large file supp
1340: 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f  ort, or if the O
1350: 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68  S is windows, th
1360: 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f  ese should be no
1370: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b  -ops..**.** Tick
1380: 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f  et #2739:  The _
1390: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
13a0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65   macro must appe
13b0: 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a  ar before any.**
13c0: 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65   system #include
13d0: 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20  s.  Hence, this 
13e0: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75  block of code mu
13f0: 73 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66  st be the very f
1400: 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20  irst.** code in 
1410: 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73  all source files
1420: 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69  ..**.** Large fi
1430: 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62  le support can b
1440: 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  e disabled using
1450: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49   the -DSQLITE_DI
1460: 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68  SABLE_LFS switch
1470: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  .** on the compi
1480: 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65  ler command line
1490: 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73  .  This is neces
14a0: 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20  sary if you are 
14b0: 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20  compiling.** on 
14c0: 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65  a recent machine
14d0: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e   (ex: Red Hat 7.
14e0: 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20  2) but you want 
14f0: 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72  your code to wor
1500: 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72  k.** on an older
1510: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
1520: 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20  d Hat 6.0).  If 
1530: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52  you compile on R
1540: 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69  ed Hat 7.2.** wi
1550: 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f  thout this optio
1560: 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65  n, LFS is enable
1570: 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20  .  But LFS does 
1580: 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65  not exist in the
1590: 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65   kernel.** in Re
15a0: 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68  d Hat 6.0, so th
15b0: 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72  e code won't wor
15c0: 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d  k.  Hence, for m
15d0: 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a  aximum binary.**
15e0: 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75   portability you
15f0: 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53   should omit LFS
1600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76  ..**.** The prev
1610: 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77  ious paragraph w
1620: 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30  as written in 20
1630: 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67  05.  (This parag
1640: 72 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a  raph is written.
1650: 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38  ** on 2008-11-28
1660: 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61  .) These days, a
1670: 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73  ll Linux kernels
1680: 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66   support large f
1690: 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20  iles, so.** you 
16a0: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20  should probably 
16b0: 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65  leave LFS enable
16c0: 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62  d.  But some emb
16d0: 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20  edded platforms 
16e0: 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46  might.** lack LF
16f0: 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  S in which case 
1700: 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42  the SQLITE_DISAB
1710: 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67  LE_LFS macro mig
1720: 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66  ht still be usef
1730: 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61  ul..**.** Simila
1740: 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61  r is true for Ma
1750: 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20  c OS X.  LFS is 
1760: 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f  only supported o
1770: 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64  n Mac OS X 9 and
1780: 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64   later..*/.#ifnd
1790: 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  ef SQLITE_DISABL
17a0: 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f  E_LFS.# define _
17b0: 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20  LARGE_FILE      
17c0: 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c   1.# ifndef _FIL
17d0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20  E_OFFSET_BITS.# 
17e0: 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f    define _FILE_O
17f0: 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20  FFSET_BITS 64.# 
1800: 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f  endif.# define _
1810: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
1820: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68   1.#endif../* Wh
1830: 61 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43  at version of GC
1840: 43 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e  C is being used.
1850: 20 20 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73    0 means GCC is
1860: 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20   not being used 
1870: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43  */.#ifdef __GNUC
1880: 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f  __.# define GCC_
1890: 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f  VERSION (__GNUC_
18a0: 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43  _*1000000+__GNUC
18b0: 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f  _MINOR__*1000+__
18c0: 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f  GNUC_PATCHLEVEL_
18d0: 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  _).#else.# defin
18e0: 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a  e GCC_VERSION 0.
18f0: 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65  #endif../* Neede
1900: 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65  d for various de
1910: 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a  finitions... */.
1920: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e  #if defined(__GN
1930: 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65  UC__) && !define
1940: 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23  d(_GNU_SOURCE).#
1950: 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55   define _GNU_SOU
1960: 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20  RCE.#endif..#if 
1970: 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53  defined(__OpenBS
1980: 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64  D__) && !defined
1990: 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20  (_BSD_SOURCE).# 
19a0: 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52  define _BSD_SOUR
19b0: 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  CE.#endif../*.**
19c0: 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63   For MinGW, chec
19d0: 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63  k to see if we c
19e0: 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68  an include the h
19f0: 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61  eader file conta
1a00: 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72  ining its.** ver
1a10: 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sion information
1a20: 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  , among other th
1a30: 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c  ings.  Normally,
1a40: 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d   this internal M
1a50: 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66  inGW.** header f
1a60: 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d  ile would [only]
1a70: 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74   be included aut
1a80: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74  omatically by ot
1a90: 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72  her MinGW header
1aa0: 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76  .** files; howev
1ab0: 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  er, the containe
1ac0: 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d  d version inform
1ad0: 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71  ation is now req
1ae0: 75 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  uired by this.**
1af0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20   header file to 
1b00: 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61  work around bina
1b10: 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ry compatibility
1b20: 20 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c   issues (see bel
1b30: 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20  ow) and.** this 
1b40: 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77  is the only know
1b50: 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c  n way to reliabl
1b60: 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68  y obtain it.  Th
1b70: 69 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c  is entire #if bl
1b80: 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20  ock.** would be 
1b90: 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63  completely unnec
1ba0: 65 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20  essary if there 
1bb0: 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61  was any other wa
1bc0: 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a  y of detecting.*
1bd0: 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69  * MinGW via thei
1be0: 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28  r preprocessor (
1bf0: 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73  e.g. if they cus
1c00: 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43  tomized their GC
1c10: 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73  C to define.** s
1c20: 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66  ome MinGW-specif
1c30: 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65  ic macros).  Whe
1c40: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  n compiling for 
1c50: 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68  MinGW, either th
1c60: 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57  e.** _HAVE_MINGW
1c70: 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e  _H or _HAVE__MIN
1c80: 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65  GW_H (note the e
1c90: 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29  xtra underscore)
1ca0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a   macro must be.*
1cb0: 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72  * defined; other
1cc0: 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20  wise, detection 
1cd0: 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70  of conditions sp
1ce0: 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20  ecific to MinGW 
1cf0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62  will be.** disab
1d00: 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  led..*/.#if defi
1d10: 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f  ned(_HAVE_MINGW_
1d20: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69  H).# include "mi
1d30: 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66  ngw.h".#elif def
1d40: 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47  ined(_HAVE__MING
1d50: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22  W_H).# include "
1d60: 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66  _mingw.h".#endif
1d70: 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47  ../*.** For MinG
1d80: 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61  W version 4.x (a
1d90: 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63  nd higher), chec
1da0: 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  k to see if the 
1db0: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f  _USE_32BIT_TIME_
1dc0: 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72  T.** define is r
1dd0: 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74  equired to maint
1de0: 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61  ain binary compa
1df0: 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68  tibility with th
1e00: 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a  e MSVC runtime.*
1e10: 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65  * library in use
1e20: 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f   (e.g. for Windo
1e30: 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21  ws XP)..*/.#if !
1e40: 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42  defined(_USE_32B
1e50: 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64  IT_TIME_T) && !d
1e60: 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49  efined(_USE_64BI
1e70: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20  T_TIME_T) && \. 
1e80: 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33     defined(_WIN3
1e90: 32 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  2) && !defined(_
1ea0: 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20  WIN64) && \.    
1eb0: 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f  defined(__MINGW_
1ec0: 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26  MAJOR_VERSION) &
1ed0: 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f  & __MINGW_MAJOR_
1ee0: 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20  VERSION >= 4 && 
1ef0: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f  \.    defined(__
1f00: 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69  MSVCRT__).# defi
1f10: 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49  ne _USE_32BIT_TI
1f20: 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  ME_T.#endif../* 
1f30: 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74  The public SQLit
1f40: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
1f50: 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42  e _FILE_OFFSET_B
1f60: 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  ITS macro must a
1f70: 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69  ppear.** first i
1f80: 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68  n QNX.  Also, th
1f90: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
1fa0: 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61  E_T macro must a
1fb0: 70 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a  ppear first for.
1fc0: 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a  ** MinGW..*/./**
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63  ************ Inc
1fe0: 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69  lude sqlite3.h i
1ff0: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
2000: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a  ***********/./**
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67  ************ Beg
2030: 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e  in file sqlite3.
2040: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a  ***********/./*.
2070: 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65  ** 2001 Septembe
2080: 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  r 15.**.** The a
2090: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
20a0: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
20b0: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
20c0: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
20d0: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
20e0: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
20f0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
2100: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
2110: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
2120: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
2130: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
2140: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
2150: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
2160: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
2170: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
2180: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
2190: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e0: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64  ***.** This head
21f0: 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20  er file defines 
2200: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68  the interface th
2210: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  at the SQLite li
2220: 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74  brary.** present
2230: 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67  s to client prog
2240: 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75  rams.  If a C-fu
2250: 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72  nction, structur
2260: 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20  e, datatype,.** 
2270: 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  or constant defi
2280: 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  nition does not 
2290: 61 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66  appear in this f
22a0: 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a  ile, then it is.
22b0: 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68  ** not a publish
22c0: 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65  ed API of SQLite
22d0: 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  , is subject to 
22e0: 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a  change without.*
22f0: 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68  * notice, and sh
2300: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65  ould not be refe
2310: 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61  renced by progra
2320: 6d 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ms that use SQLi
2330: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  te..**.** Some o
2340: 66 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  f the definition
2350: 73 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68  s that are in th
2360: 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b  is file are mark
2370: 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69  ed as.** "experi
2380: 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69  mental".  Experi
2390: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
23a0: 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e  s are normally n
23b0: 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72  ew.** features r
23c0: 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f  ecently added to
23d0: 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20   SQLite.  We do 
23e0: 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63  not anticipate c
23f0: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70  hanges.** to exp
2400: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
2410: 61 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65  aces but reserve
2420: 20 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61   the right to ma
2430: 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73  ke minor changes
2440: 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63  .** if experienc
2450: 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74  e from use "in t
2460: 68 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74  he wild" suggest
2470: 20 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72   such changes ar
2480: 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a  e prudent..**.**
2490: 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d   The official C-
24a0: 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63  language API doc
24b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53  umentation for S
24c0: 51 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64  QLite is derived
24d0: 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74  .** from comment
24e0: 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20  s in this file. 
24f0: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68   This file is th
2500: 65 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20  e authoritative 
2510: 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77  source.** on how
2520: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2530: 65 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20  es are supposed 
2540: 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a  to operate..**.*
2550: 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
2560: 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f  is file under co
2570: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
2580: 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74  gement is "sqlit
2590: 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20  e.h.in"..** The 
25a0: 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73  makefile makes s
25b0: 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65  ome minor change
25c0: 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28  s to this file (
25d0: 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e  such as insertin
25e0: 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e  g.** the version
25f0: 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61   number) and cha
2600: 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f  nges its name to
2610: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a   "sqlite3.h" as.
2620: 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  ** part of the b
2630: 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f  uild process..*/
2640: 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45  .#ifndef _SQLITE
2650: 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51  3_H_.#define _SQ
2660: 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64  LITE3_H_.#includ
2670: 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20  e <stdarg.h>    
2680: 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74   /* Needed for t
2690: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66  he definition of
26a0: 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a   va_list */../*.
26b0: 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20  ** Make sure we 
26c0: 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74  can call this st
26d0: 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f  uff from C++..*/
26e0: 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43  .#if 0.extern "C
26f0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
2700: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
2710: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
2720: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
2730: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
2740: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
2750: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
2760: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
2770: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
2780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
2790: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
27a0: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
27b0: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
27c0: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
27d0: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
27e0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
27f0: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
2800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
2810: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
2820: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
2830: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
2840: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
2850: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
2860: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2870: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
2880: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
2890: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
28a0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
28b0: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
28c0: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
28d0: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
28e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
28f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2900: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
2910: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
2920: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
2930: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
2940: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
2950: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
2960: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
2970: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
2980: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
2990: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
29a0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
29b0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
29c0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
29d0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
29e0: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
29f0: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
2a00: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
2a10: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
2a20: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
2a30: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
2a40: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
2a50: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
2a60: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
2a70: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
2a80: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
2a90: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
2aa0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
2ab0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
2ac0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
2ad0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
2ae0: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
2af0: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
2b00: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
2b10: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
2b20: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
2b30: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
2b40: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
2b50: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
2b60: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
2b70: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
2b80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
2b90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2ba0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
2bb0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
2bc0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
2bd0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
2be0: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
2bf0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
2c00: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
2c10: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
2c20: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
2c30: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
2c40: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c50: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
2c60: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
2c70: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
2c80: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
2c90: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
2ca0: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
2cb0: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
2cc0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
2cd0: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
2ce0: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
2cf0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
2d00: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
2d10: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
2d20: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
2d30: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
2d40: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
2d50: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
2d60: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
2d70: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
2d80: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
2d90: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
2da0: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
2db0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
2dc0: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
2dd0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2de0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
2df0: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
2e00: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
2e10: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
2e20: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
2e30: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
2e40: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
2e50: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
2e60: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
2e70: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
2e80: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
2e90: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
2ea0: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
2eb0: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
2ec0: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
2ed0: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
2ee0: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
2ef0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
2f00: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
2f10: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
2f20: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
2f30: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
2f40: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
2f50: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
2f60: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
2f70: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
2f80: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
2f90: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
2fa0: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
2fb0: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
2fc0: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
2fd0: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
2fe0: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
2ff0: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
3000: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
3010: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
3020: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
3030: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
3040: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
3050: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
3060: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
3070: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
3080: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
3090: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
30a0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
30b0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
30c0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
30d0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
30e0: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
30f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
3100: 20 20 20 20 20 22 33 2e 38 2e 31 32 22 0a 23 64       "3.8.12".#d
3110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
3120: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38  SION_NUMBER 3008
3130: 30 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  012.#define SQLI
3140: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
3150: 20 20 22 32 30 31 35 2d 30 39 2d 32 38 20 31 37    "2015-09-28 17
3160: 3a 30 35 3a 32 32 20 63 35 35 36 36 62 62 33 39  :05:22 c5566bb39
3170: 63 38 64 39 62 35 38 66 37 37 33 38 30 62 38 31  c8d9b58f77380b81
3180: 61 38 37 33 34 32 39 35 37 35 63 37 64 35 63 22  a873429575c7d5c"
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 4c 4f 43 4b 45  ine SQLITE_LOCKE
7760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
7770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
7780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
7790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
77a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
77b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
77c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
77d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
77e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
77f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
7800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
7810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
7820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
7830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
7840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
7850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
7870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
7890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
78a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
78b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
78c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
78d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
78e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
78f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
7900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
7920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
7930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
7940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
7950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
7970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
7980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
7990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
79a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
79b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
79c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
79d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
79e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
79f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
7a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
7a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
7a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
7a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
7a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
7a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
7aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
7ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
7ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
7b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
7b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
7b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
7b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
7b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
7bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
7bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
7bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
7c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
7c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
7c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
7c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
7ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
7cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
7ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
7d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
7d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
7d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
7d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
7d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
7d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
7db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
7de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
7df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
7e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
7e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
7e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
7e40: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
7e50: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
7e60: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
7e70: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
7e80: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
7e90: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
7ea0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
7eb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
7ec0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
7ed0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
7ee0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
7ef0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
7f00: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7f10: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
7f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f30: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
7f40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
7f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f80: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
7f90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
7fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7fd0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
7fe0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
7ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8020: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8030: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
8040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8060: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
8070: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
8080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80a0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
80b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
80c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
80d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80e0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
80f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
8100: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8110: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8130: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
8140: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
8150: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8160: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8180: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
8190: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
81a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
81b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
81c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
81d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
81e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
81f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8200: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
8210: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
8220: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8240: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
8250: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
8260: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8280: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8290: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
82a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
82b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
82c0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
82d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
82e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
82f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8300: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
8310: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
8320: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8340: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
8350: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
8360: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8370: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8390: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
83a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
83b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
83c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
83d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83e0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
83f0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
8400: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8410: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8430: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
8440: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
8450: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8480: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
8490: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
84a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
84b0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
84c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
84d0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
84e0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
84f0: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
8500: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
8510: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
8520: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
8530: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
8540: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8550: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
8560: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
8570: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
8580: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
8590: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
85a0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
85b0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
85c0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
85d0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
85e0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
85f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8600: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
8610: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
8620: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8630: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8640: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8650: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8660: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8680: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8690: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
86a0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
86b0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
86c0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
86d0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
86e0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
86f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8700: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8710: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8720: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8730: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8740: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8750: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8760: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
8770: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8780: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8790: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
87a0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
87b0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
87c0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
87d0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
87e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
87f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8800: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8810: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8820: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8830: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8840: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8850: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8860: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8870: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
8880: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
8890: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
88a0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
88b0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
88c0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
88d0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
88e0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
88f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
8900: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
8910: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
8920: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
8930: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
8940: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
8950: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
8960: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
8970: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
8980: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8990: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
89a0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
89b0: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
89c0: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
89d0: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
89e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
89f0: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
8a00: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
8a10: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
8a20: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
8a30: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
8a40: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
8a50: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
8a60: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
8a70: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
8a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a90: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
8aa0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
8ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8ac0: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
8ad0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8ae0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
8af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8b00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8b10: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
8b20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8b30: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
8b40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
8b50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
8b60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
8b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8b80: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
8b90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8ba0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
8bb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
8bc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8bd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
8be0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8bf0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
8c00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8c10: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
8c20: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
8c30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8c40: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
8c50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8c60: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
8c70: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8c80: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
8c90: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
8ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8cb0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
8cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
8cd0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8ce0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
8cf0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
8d00: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
8d10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
8d20: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8d30: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
8d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d50: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
8d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8d70: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
8d80: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
8d90: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
8da0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
8db0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
8dc0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
8dd0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
8de0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
8df0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
8e00: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
8e10: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
8e20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
8e30: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8e40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8e50: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
8e60: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
8e70: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
8e80: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
8e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8ea0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
8eb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ec0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
8ed0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8ef0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
8f00: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
8f10: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
8f20: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
8f30: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
8f40: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
8f50: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
8f60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8f70: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
8f80: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
8f90: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
8fa0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
8fb0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
8fc0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
8fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
8fe0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
8ff0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
9000: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
9010: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
9020: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
9030: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
9040: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
9050: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
9060: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
9070: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
9080: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
9090: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
90a0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
90b0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
90c0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
90d0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
90e0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
90f0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
9100: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
9110: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
9120: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
9130: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
9140: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
9150: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
9160: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
9170: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
9180: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
9190: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
91a0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
91b0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
91c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
91d0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
91e0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
91f0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
9200: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
9210: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
9220: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
9230: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
9240: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
9250: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
9260: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
9270: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
9280: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
9290: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
92a0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
92b0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
92c0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
92d0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
92e0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
92f0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
9300: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
9310: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
9320: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
9330: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
9340: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
9350: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
9360: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
9370: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
9380: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
9390: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
93a0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
93b0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
93c0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
93d0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
93e0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
93f0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
9400: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
9410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9420: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
9430: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
9440: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
9450: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
9460: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
9470: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
9480: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
9490: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
94a0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
94b0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
94c0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
94d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
94e0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
94f0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
9500: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
9510: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
9520: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
9530: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
9540: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
9550: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
9560: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
9570: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
9580: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
9590: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
95a0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
95b0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
95c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
95d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
95e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
95f0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
9600: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
9610: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
9620: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
9630: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
9640: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
9650: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
9660: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
9670: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
9680: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
9690: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
96a0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
96b0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
96c0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
96d0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
96e0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
96f0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
9700: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
9710: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
9720: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
9730: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
9740: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
9750: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9760: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
9770: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
9780: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
9790: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
97a0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
97b0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
97c0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
97d0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
97e0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
97f0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
9800: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
9810: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
9820: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
9830: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
9840: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9850: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
9860: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
9870: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
9880: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
9890: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
98a0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
98b0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
98c0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
98d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
98e0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
98f0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
9900: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
9910: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
9920: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
9930: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
9940: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
9950: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
9960: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
9970: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
9980: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
9990: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
99a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
99b0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
99c0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
99d0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
99e0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
99f0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
9a00: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
9a10: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
9a20: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
9a30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
9a40: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
9a50: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
9a60: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
9a70: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
9a80: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
9a90: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
9aa0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
9ab0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
9ac0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
9ad0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
9ae0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
9af0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
9b00: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
9b10: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
9b20: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
9b30: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
9b40: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
9b50: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
9b60: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
9b70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9b80: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
9b90: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
9ba0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
9bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9bc0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
9bd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9be0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
9bf0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9c00: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
9c10: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
9c20: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9c30: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
9c40: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
9c50: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
9c60: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
9c70: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
9c80: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
9c90: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
9ca0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
9cb0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
9cc0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
9cd0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
9ce0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
9cf0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
9d00: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
9d10: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
9d20: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
9d30: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
9d40: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
9d50: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
9d60: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
9d70: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
9d80: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
9d90: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
9da0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9db0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
9dc0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
9dd0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
9de0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9df0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
9e00: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
9e10: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
9e20: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
9e30: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
9e40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
9e50: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
9e60: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
9e70: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
9e80: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
9e90: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
9ea0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
9eb0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
9ec0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
9ed0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
9ee0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
9ef0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
9f00: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
9f10: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
9f20: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
9f30: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
9f40: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
9f50: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
9f60: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
9f70: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
9f80: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
9f90: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
9fa0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
9fb0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
9fc0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
9fd0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
9fe0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
9ff0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
a000: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
a010: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
a020: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
a030: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
a040: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
a050: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
a060: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
a070: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
a080: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
a090: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
a0a0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
a0b0: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
a0c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
a0d0: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
a0e0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a0f0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
a100: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
a110: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
a120: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
a130: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
a140: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a150: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
a160: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
a170: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
a180: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
a190: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
a1a0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
a1b0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
a1c0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
a1d0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
a1e0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
a1f0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
a200: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a210: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
a220: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
a230: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
a240: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
a250: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
a260: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
a270: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a280: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
a2a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
a2b0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
a2c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a2d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a2e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
a2f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a300: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
a310: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a320: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
a330: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a340: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a350: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
a360: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a370: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
a380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a390: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
a3a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
a3b0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
a3c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
a3d0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
a3e0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
a3f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a400: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
a410: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
a420: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
a430: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
a450: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
a460: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
a470: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
a480: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
a490: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
a4a0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
a4b0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
a4c0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
a4d0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
a4e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a4f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
a500: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
a510: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
a520: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
a530: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
a540: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
a550: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
a560: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
a570: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
a580: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
a590: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
a5a0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
a5b0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
a5c0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a5d0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
a5e0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
a5f0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
a600: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
a610: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
a620: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
a630: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
a640: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
a650: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
a660: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
a670: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
a680: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
a690: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
a6a0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
a6b0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
a6c0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
a6d0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
a6e0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
a6f0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
a700: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
a710: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
a720: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
a730: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
a740: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a750: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
a760: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
a770: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a780: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
a790: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
a7a0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
a7b0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a7c0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
a7d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
a7e0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a7f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a800: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
a810: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a820: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
a830: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
a840: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
a850: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
a860: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
a870: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
a880: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
a890: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
a8a0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
a8b0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
a8c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
a8e0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
a8f0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
a900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
a910: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
a920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a930: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
a940: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
a950: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a960: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
a970: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
a980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a990: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
a9a0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
a9b0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
a9c0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
a9d0: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
a9e0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
a9f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
aa00: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
aa10: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
aa20: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
aa30: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
aa40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
aa50: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
aa60: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
aa70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
aa80: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
aa90: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
aaa0: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
aab0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
aac0: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
aad0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
aae0: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
aaf0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
ab00: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
ab10: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
ab20: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
ab30: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
ab40: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
ab50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
ab60: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
ab70: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
ab80: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
ab90: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
aba0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
abb0: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
abc0: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
abd0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
abe0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
abf0: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
ac00: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
ac10: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ac20: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
ac30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ac40: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
ac50: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
ac60: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
ac70: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
ac80: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
ac90: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
aca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
acb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
acc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
acd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
ace0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
acf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
ad00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
ad10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ad20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
ad30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
ad40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
ad50: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
ad60: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
ad70: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ad80: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
ad90: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
ada0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
adb0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
adc0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
add0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
ade0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
adf0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
ae00: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
ae10: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
ae20: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
ae30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
ae40: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
ae50: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
ae60: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
ae70: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
ae80: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
ae90: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
aea0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
aeb0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
aec0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
aed0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
aee0: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
aef0: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
af00: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
af10: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
af20: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
af30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
af40: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
af50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
af60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
af70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
af80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
af90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
afa0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
afb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
afc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
afd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
afe0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
aff0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
b000: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
b010: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
b020: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
b030: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
b040: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
b050: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
b060: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
b070: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
b080: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
b090: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
b0a0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
b0b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
b0c0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
b0d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b0e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b0f0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b110: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
b120: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
b130: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
b140: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
b150: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
b160: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
b170: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
b180: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
b190: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
b1a0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
b1b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b1c0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
b1d0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
b1e0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
b1f0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
b200: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
b210: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
b220: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
b230: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
b240: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
b250: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
b260: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
b270: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
b280: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
b290: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
b2a0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
b2b0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
b2c0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
b2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b2e0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b2f0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b310: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
b320: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
b330: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
b340: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b350: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
b360: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
b370: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
b380: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
b390: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
b3a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b3b0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
b3c0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
b3d0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
b3e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b400: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c  MITTED]].** No l
b410: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a  onger in use..**
b420: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b430: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a  _FCNTL_SYNC]].**
b440: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b450: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20  TL_SYNC] opcode 
b460: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
b470: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
b480: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f  e and.** sent to
b490: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61   the VFS immedia
b4a0: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20  tely before the 
b4b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
b4c0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20  invoked on a.** 
b4d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65  database file de
b4e0: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66  scriptor. Or, if
b4f0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b500: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  d is not invoked
b510: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65   .** because the
b520: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67   user has config
b530: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68  ured SQLite with
b540: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e   .** [PRAGMA syn
b550: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
b560: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
b570: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  F] it is invoked
b580: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66   in place .** of
b590: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b5a0: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73  d. In most cases
b5b0: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72  , the pointer ar
b5c0: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69  gument passed wi
b5d0: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d  th.** this file-
b5e0: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e  control is NULL.
b5f0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
b600: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b610: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a  s being synced.*
b620: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d  * as part of a m
b630: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f  ulti-database co
b640: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65  mmit, the argume
b650: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e  nt points to a n
b660: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
b670: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
b680: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ng the transacti
b690: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e  ons master-journ
b6a0: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46  al file name. VF
b6b0: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20  Ses that .** do 
b6c0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
b6d0: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65  gnal should sile
b6e0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b6f0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b700: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64  tions .** should
b710: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
b720: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b730: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
b740: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
b750: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20  may .** disrupt 
b760: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
b770: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
b780: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
b790: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
b7a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b7b0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
b7c0: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b  SETWO]].** The [
b7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b7e0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70  MIT_PHASETWO] op
b7f0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
b800: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
b810: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65  SQLite.** and se
b820: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66  nt to the VFS af
b830: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ter a transactio
b840: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69  n has been commi
b850: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  tted immediately
b860: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74  .** but before t
b870: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75  he database is u
b880: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74  nlocked. VFSes t
b890: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  hat do not need 
b8a0: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73  this signal.** s
b8b0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
b8c0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
b8d0: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
b8e0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a  should not call.
b8f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
b900: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
b910: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
b920: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
b930: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65  rupt the .** ope
b940: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
b950: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
b960: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
b970: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
b980: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b990: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
b9a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b9b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b9c0: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
b9d0: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
b9e0: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
b9f0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
ba00: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
ba10: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
ba20: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
ba30: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
ba40: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
ba50: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
ba60: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
ba70: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
ba80: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
ba90: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
baa0: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
bab0: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
bac0: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
bad0: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
bae0: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
baf0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
bb00: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
bb10: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
bb20: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
bb30: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
bb40: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
bb50: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
bb60: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
bb70: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
bb80: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
bb90: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bba0: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
bbb0: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
bbc0: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
bbd0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
bbe0: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
bbf0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
bc00: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
bc10: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
bc20: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
bc30: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
bc40: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
bc50: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
bc60: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
bc70: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
bc80: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
bc90: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
bca0: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
bcb0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
bcc0: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
bcd0: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
bce0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
bcf0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
bd00: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
bd10: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
bd20: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
bd30: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
bd40: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
bd50: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
bd60: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
bd70: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
bd80: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
bd90: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
bda0: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
bdb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
bdc0: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
bdd0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bde0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
bdf0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
be00: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
be10: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
be20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
be30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
be40: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
be50: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
be60: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
be70: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
be80: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
be90: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
bea0: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
beb0: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
bec0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
bed0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
bee0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
bef0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
bf00: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
bf10: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
bf20: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
bf30: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
bf40: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
bf50: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
bf60: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
bf70: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
bf80: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
bf90: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
bfa0: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
bfb0: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
bfc0: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
bfd0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
bfe0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
bff0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
c000: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
c010: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
c020: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
c030: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
c040: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
c050: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
c060: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
c070: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
c080: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
c090: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c0a0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
c0b0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
c0c0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
c0d0: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
c0e0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
c0f0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
c100: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
c110: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
c120: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
c130: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c140: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c150: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c160: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c170: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
c180: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
c190: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c1a0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
c1b0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
c1c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c1d0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c1e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
c1f0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
c200: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
c210: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
c220: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
c230: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
c240: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
c250: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
c260: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
c270: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c280: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
c290: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
c2a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
c2b0: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
c2c0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
c2d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c2e0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
c2f0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
c300: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c310: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
c320: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
c330: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
c340: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
c350: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
c360: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
c370: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c380: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c390: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c3a0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c3b0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
c3c0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
c3d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c3e0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
c3f0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c400: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
c410: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
c420: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
c430: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
c440: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
c450: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c460: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
c470: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
c480: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
c490: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
c4a0: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
c4b0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
c4c0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
c4d0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
c4e0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
c4f0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
c500: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c510: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c520: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
c530: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c540: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c550: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c560: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
c570: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
c580: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
c590: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
c5a0: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
c5b0: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
c5c0: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
c5d0: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
c5e0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
c5f0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
c600: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
c610: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
c620: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
c630: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
c640: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
c650: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
c660: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c670: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
c680: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
c690: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
c6a0: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
c6b0: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
c6c0: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
c6d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
c6e0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
c6f0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
c700: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
c710: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
c720: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
c730: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
c740: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
c750: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
c760: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
c770: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
c780: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
c790: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
c7a0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
c7b0: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
c7c0: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
c7d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c7e0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
c7f0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
c800: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
c810: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
c820: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c830: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
c840: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
c850: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
c860: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
c870: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
c880: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
c890: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
c8a0: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
c8b0: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
c8c0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
c8d0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
c8e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
c8f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
c900: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
c910: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
c920: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
c930: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
c940: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
c950: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
c960: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
c970: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
c980: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
c990: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
c9a0: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
c9b0: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
c9c0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
c9d0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
c9e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c9f0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ca00: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
ca10: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
ca20: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
ca30: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
ca40: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
ca50: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
ca60: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ca70: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
ca80: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
ca90: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
caa0: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
cab0: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
cac0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
cad0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
cae0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
caf0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
cb00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cb10: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
cb20: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
cb30: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
cb40: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
cb50: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
cb60: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
cb70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb80: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
cb90: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
cba0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
cbb0: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
cbc0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
cbd0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
cbe0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
cbf0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
cc00: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
cc10: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
cc20: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
cc30: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
cc40: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
cc50: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
cc60: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
cc70: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
cc80: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
cc90: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
cca0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ccb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ccc0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
ccd0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
cce0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
ccf0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
cd00: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
cd10: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
cd20: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
cd30: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
cd40: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
cd50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
cd60: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
cd70: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
cd80: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
cd90: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
cda0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
cdb0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
cdc0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
cdd0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
cde0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
cdf0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
ce00: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
ce10: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
ce20: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
ce30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ce40: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ce50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ce60: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
ce70: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
ce80: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
ce90: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
cea0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
ceb0: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
cec0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
ced0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
cee0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
cef0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
cf00: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
cf10: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
cf20: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
cf30: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
cf40: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
cf50: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
cf60: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
cf70: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
cf80: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
cf90: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
cfa0: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
cfb0: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
cfc0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
cfd0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
cfe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
cff0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
d000: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
d010: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
d020: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
d030: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
d040: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
d050: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
d060: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
d070: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
d080: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
d090: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
d0a0: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
d0b0: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
d0c0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
d0d0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
d0e0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
d0f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
d110: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
d120: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
d130: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
d140: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
d150: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
d160: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
d170: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
d180: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
d190: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
d1a0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
d1b0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
d1c0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
d1d0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
d1e0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
d1f0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
d200: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
d210: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
d220: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
d230: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
d240: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
d250: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
d260: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
d270: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
d280: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
d290: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
d2a0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
d2b0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
d2c0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
d2d0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
d2e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d2f0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
d300: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d310: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
d320: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
d330: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
d340: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
d350: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
d360: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
d370: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
d380: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
d390: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
d3a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
d3b0: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
d3c0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
d3d0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
d3e0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
d3f0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
d400: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
d410: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
d420: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
d430: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
d440: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
d450: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
d460: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
d470: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
d480: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
d490: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
d4a0: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
d4b0: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
d4c0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
d4d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
d4e0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
d4f0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
d500: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
d510: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
d520: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
d530: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
d540: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d550: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
d560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
d570: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
d580: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
d590: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
d5a0: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
d5b0: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
d5c0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
d5d0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
d5e0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
d5f0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d600: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
d610: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
d620: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
d630: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
d640: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
d650: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
d660: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
d670: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
d680: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
d690: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
d6a0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
d6b0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
d6c0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
d6d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d6e0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
d6f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d700: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
d710: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
d720: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
d730: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
d740: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
d750: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
d760: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
d770: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
d780: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
d790: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
d7a0: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
d7b0: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
d7c0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
d7d0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
d7e0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
d7f0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
d800: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
d810: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d820: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
d830: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
d840: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d850: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
d860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
d870: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
d880: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
d890: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
d8a0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
d8b0: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
d8c0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
d8d0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
d8e0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
d8f0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
d900: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
d910: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
d920: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
d930: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
d940: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
d950: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
d960: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d970: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
d980: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d990: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
d9a0: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
d9b0: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
d9c0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
d9d0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
d9e0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
d9f0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
da00: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
da10: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
da20: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
da30: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
da40: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
da50: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
da60: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
da70: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
da80: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
da90: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
daa0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
dab0: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
dac0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
dad0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
dae0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
daf0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
db00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
db10: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
db20: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
db30: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
db40: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
db50: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
db60: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
db70: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
db80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
db90: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
dba0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
dbb0: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
dbc0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
dbd0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
dbe0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
dbf0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
dc00: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
dc10: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
dc20: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
dc30: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
dc40: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ode.  .** </ul>.
dc50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dc60: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
dc70: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
dc80: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
dc90: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dca0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
dcb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dcc0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
dcd0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
dce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dcf0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
dd00: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
dd10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dd20: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
dd30: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
dd40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dd50: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
dd60: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
dd70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dd80: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
dd90: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
dda0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ddb0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
ddc0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
ddd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dde0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
ddf0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
de00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
de10: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
de20: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
de30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
de40: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
de50: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
de60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
de70: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
de80: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
de90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
dea0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
deb0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
dec0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ded0: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
dee0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
def0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
df00: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
df10: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
df20: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
df30: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
df40: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
df50: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
df60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
df70: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
df80: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
df90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
dfa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dfb0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
dfc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
dfd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dfe0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
dff0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
e000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e010: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
e020: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
e030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e040: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
e050: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
e060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e070: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
e080: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
e090: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e0a0: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
e0b0: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
e0c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e0d0: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
e0e0: 20 20 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65         26../* de
e0f0: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
e100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e110: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
e120: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
e130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
e140: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
e150: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
e160: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
e170: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
e180: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
e190: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
e1a0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
e1b0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
e1c0: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
e1d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
e1e0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
e1f0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
e200: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
e210: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
e220: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
e230: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
e240: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
e250: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
e260: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
e270: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
e280: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
e290: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
e2a0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
e2b0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
e2c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
e2d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
e2e0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
e2f0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
e300: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
e310: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
e320: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e330: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
e340: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
e350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e360: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
e370: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
e380: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
e390: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e3a0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
e3b0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
e3c0: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
e3d0: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
e3e0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
e3f0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
e400: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
e410: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
e420: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
e430: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
e440: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
e450: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
e460: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
e470: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
e480: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
e490: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
e4a0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
e4b0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
e4c0: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
e4d0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
e4e0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
e4f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
e500: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
e510: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
e520: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
e530: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
e540: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
e550: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
e560: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
e570: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
e580: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
e590: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
e5a0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
e5b0: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
e5c0: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
e5d0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
e5e0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
e5f0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
e600: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
e610: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
e620: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
e630: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
e640: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
e650: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
e660: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
e670: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
e680: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
e690: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
e6a0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
e6b0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
e6c0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
e6d0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
e6e0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
e6f0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
e700: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
e710: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
e720: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
e730: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
e740: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
e750: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
e760: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
e770: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
e780: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
e790: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
e7a0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
e7b0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
e7c0: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
e7d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
e7e0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
e7f0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
e800: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
e810: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
e820: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
e830: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
e840: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
e850: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
e860: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
e870: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
e880: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
e890: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
e8a0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
e8b0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
e8c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
e8d0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
e8e0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
e8f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
e900: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
e910: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
e920: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
e930: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
e940: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
e950: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
e960: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
e970: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
e980: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
e990: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
e9a0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
e9b0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e9c0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e9d0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e9e0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e9f0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
ea00: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
ea10: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
ea20: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
ea30: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
ea40: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
ea50: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
ea60: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
ea70: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
ea80: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ea90: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
eaa0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
eab0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
eac0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
ead0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
eae0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
eaf0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
eb00: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
eb10: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
eb20: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
eb30: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
eb40: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
eb50: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
eb60: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
eb70: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
eb80: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
eb90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
eba0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
ebb0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
ebc0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
ebd0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
ebe0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ebf0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ec00: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ec10: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ec20: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ec30: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ec40: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
ec50: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
ec60: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ec70: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
ec80: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
ec90: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
eca0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
ecb0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
ecc0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
ecd0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
ece0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
ecf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ed00: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
ed10: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
ed20: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
ed30: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
ed40: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
ed50: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ed60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
ed70: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ed80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ed90: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
eda0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
edb0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
edc0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
edd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
ede0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
edf0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
ee00: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
ee10: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
ee20: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
ee30: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
ee40: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
ee50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
ee60: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
ee70: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
ee80: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
ee90: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
eea0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
eeb0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
eec0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
eed0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
eee0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
eef0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
ef00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
ef10: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ef20: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
ef30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ef40: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
ef50: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ef60: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
ef70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ef80: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
ef90: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
efa0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
efb0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
efc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
efd0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
efe0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
eff0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
f000: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
f010: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
f020: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
f030: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
f040: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
f050: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
f060: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
f070: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
f080: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
f090: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
f0a0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
f0b0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
f0c0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
f0d0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
f0e0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
f0f0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
f100: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
f110: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
f120: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
f130: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
f140: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
f150: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
f160: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
f170: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
f180: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
f190: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
f1a0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
f1b0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
f1c0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
f1d0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
f1e0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
f1f0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
f200: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
f210: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
f220: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
f230: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
f240: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
f250: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
f260: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
f270: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
f280: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
f290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
f2a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f2b0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
f2c0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2d0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
f2e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
f2f0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f300: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
f310: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f320: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
f330: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
f340: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
f350: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f360: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
f370: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
f380: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
f390: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
f3a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
f3b0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
f3c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
f3d0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f3e0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
f3f0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
f400: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
f410: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
f420: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
f430: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
f440: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
f450: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
f460: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
f470: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
f480: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
f490: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
f4a0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
f4b0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
f4c0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
f4d0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
f4e0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f4f0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
f500: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
f510: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
f520: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
f530: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
f540: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
f550: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
f560: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
f570: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
f580: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
f590: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
f5a0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
f5b0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
f5c0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
f5d0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
f5e0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
f5f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
f600: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
f610: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
f620: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f630: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
f640: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
f650: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
f660: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
f670: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
f680: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
f690: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
f6a0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
f6b0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
f6c0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
f6d0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
f6e0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
f6f0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
f700: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
f710: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
f720: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
f730: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
f740: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
f750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f760: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
f770: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
f780: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
f790: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
f7a0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
f7b0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
f7c0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
f7d0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f7e0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
f7f0: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
f800: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
f810: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
f820: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
f830: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
f840: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
f850: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
f860: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f870: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
f880: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f890: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
f8a0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
f8b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
f8c0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
f8d0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
f8e0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
f8f0: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
f900: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
f910: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
f920: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
f930: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
f940: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
f950: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
f960: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
f970: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
f980: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
f990: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f9a0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
f9b0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f9c0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f9d0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f9e0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f9f0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
fa00: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
fa10: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
fa20: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
fa30: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
fa40: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
fa50: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
fa60: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
fa70: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
fa80: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
fa90: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
faa0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
fab0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
fac0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
fad0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
fae0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
faf0: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
fb00: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
fb10: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
fb20: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
fb30: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
fb40: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
fb50: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
fb60: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
fb70: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
fb80: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
fb90: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
fba0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
fbb0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
fbc0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
fbd0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
fbe0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
fbf0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
fc00: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
fc10: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
fc20: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
fc30: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
fc40: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
fc50: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
fc60: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
fc70: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
fc80: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
fc90: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
fca0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
fcb0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
fcc0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
fcd0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
fce0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
fcf0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
fd00: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
fd10: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
fd20: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
fd30: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fd40: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
fd50: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
fd60: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
fd70: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
fd80: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
fd90: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
fda0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
fdb0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
fdc0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
fdd0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
fde0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fdf0: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
fe00: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
fe10: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
fe20: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
fe30: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
fe40: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
fe50: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
fe60: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fe70: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
fe80: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
fe90: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
fea0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
feb0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
fec0: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
fed0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
fee0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
fef0: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
ff00: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
ff10: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
ff20: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
ff30: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
ff40: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
ff50: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
ff60: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
ff70: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
ff80: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
ff90: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
ffa0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
ffb0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
ffc0: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
ffd0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
ffe0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
fff0: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
10000 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
10010 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
10020 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
10030 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
10040 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
10050 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
10060 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
10070 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
10080 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
10090 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
100a0 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
100b0 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
100c0 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
100d0 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
100e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
100f0 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
10100 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
10110 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
10120 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
10130 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
10140 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
10150 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
10160 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
10170 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
10180 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
10190 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
101a0 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
101b0 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
101c0 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
101d0 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
101e0 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
101f0 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
10200 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
10210 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
10220 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
10230 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
10240 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
10250 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
10260 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
10270 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
10280 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
10290 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
102a0 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
102b0 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
102c0 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
102d0 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
102e0 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
102f0 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
10300 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
10310 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
10320 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
10330 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
10340 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
10350 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
10360 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
10370 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
10380 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
10390 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
103a0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
103b0 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
103c0 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
103d0 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
103e0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
103f0 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
10400 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10410 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
10420 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
10430 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
10440 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
10450 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
10460 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10470 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10480 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
10490 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
104a0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
104b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
104c0 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
104d0 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
104e0 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
104f0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10500 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10510 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
10520 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
10530 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
10540 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10550 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
10560 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
10570 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
10580 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10590 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
105a0 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
105b0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
105c0 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
105d0 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
105e0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
105f0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
10600 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
10610 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
10620 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
10630 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
10640 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
10650 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
10660 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
10670 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
10680 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
10690 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
106a0 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
106b0 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
106c0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
106d0 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
106e0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
106f0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
10700 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
10710 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
10720 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
10730 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
10740 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
10750 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
10760 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
10770 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
10780 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10790 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
107a0 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
107b0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
107c0 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
107d0 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
107e0 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
107f0 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
10800 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
10810 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
10820 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
10830 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10840 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10850 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
10860 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10870 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
10880 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
10890 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
108a0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
108b0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
108c0 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
108d0 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
108e0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
108f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
10900 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
10910 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
10920 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
10930 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
10940 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
10950 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
10960 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
10970 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
10980 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
10990 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
109a0 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
109b0 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
109c0 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
109d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
109e0 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
109f0 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
10a00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
10a10 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
10a20 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
10a30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
10a40 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
10a50 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
10a60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
10a70 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
10a80 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
10a90 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
10aa0 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
10ab0 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10ac0 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10ad0 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10ae0 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10af0 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10b00 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10b10 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10b20 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10b30 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
10b40 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b50 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10b60 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
10b70 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
10b80 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
10b90 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
10ba0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
10bb0 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10bc0 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10bd0 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10be0 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10bf0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10c00 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10c10 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10c20 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10c30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10c40 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10c50 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
10c60 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
10c70 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10c80 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
10c90 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
10ca0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
10cb0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10cc0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10cd0 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10ce0 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10cf0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10d00 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10d10 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10d20 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10d30 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10d40 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10d50 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
10d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10d70 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10d80 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
10d90 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10da0 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
10db0 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10dc0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10de0 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10df0 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10e00 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10e10 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10e20 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10e30 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10e40 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10e50 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10e60 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10e70 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10e80 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
10e90 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
10ea0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
10eb0 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10ec0 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10ed0 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10ee0 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10ef0 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10f00 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10f10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10f20 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10f30 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10f40 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10f50 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10f60 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10f70 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10f80 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10f90 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10fa0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10fb0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10fc0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10fd0 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10fe0 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10ff0 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
11000 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
11010 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
11020 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
11030 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
11040 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
11050 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
11060 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
11070 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
11080 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
11090 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
110a0 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
110b0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
110c0 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
110d0 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
110e0 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
110f0 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
11100 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
11110 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
11120 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
11130 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
11140 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
11150 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
11160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11170 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
11180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11190 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
111a0 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
111b0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
111c0 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
111d0 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
111e0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
111f0 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
11200 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
11210 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
11220 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
11230 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
11240 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
11250 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
11260 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
11270 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
11280 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11290 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
112a0 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
112b0 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
112c0 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
112d0 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
112e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
112f0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
11300 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
11310 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11320 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
11330 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
11340 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
11350 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
11360 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
11370 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
11380 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
11390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
113a0 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
113b0 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
113c0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
113d0 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
113e0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
113f0 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
11400 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
11410 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
11420 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
11430 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
11440 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
11450 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
11460 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11470 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
11480 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
11490 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
114a0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
114b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
114c0 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
114d0 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
114e0 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
114f0 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
11500 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
11510 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11520 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
11530 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
11540 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
11550 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
11560 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
11570 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
11580 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
11590 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
115a0 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
115b0 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
115c0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
115d0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
115e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
115f0 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
11600 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
11610 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
11620 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11630 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
11640 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
11650 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
11660 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
11670 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
11680 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11690 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
116a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
116b0 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
116c0 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
116d0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
116e0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
116f0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
11700 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11710 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
11720 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
11730 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11740 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
11750 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
11760 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
11770 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
11780 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
11790 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
117a0 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
117b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
117c0 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
117d0 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
117e0 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
117f0 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
11800 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
11810 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
11820 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
11830 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
11840 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
11850 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
11860 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
11870 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
11880 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
11890 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
118a0 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
118b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
118c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
118d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
118e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
118f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11900 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
11910 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
11920 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11930 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
11940 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
11950 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
11960 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
11970 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
11980 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
11990 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
119a0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
119b0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
119c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
119d0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
119e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
119f0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
11a00 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
11a10 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
11a20 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
11a30 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
11a40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
11a50 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
11a60 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
11a70 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11a80 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
11a90 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
11aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
11ab0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11ac0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11ad0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11ae0 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11af0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11b00 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11b10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11b20 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11b30 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
11b40 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
11b50 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
11b60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11b70 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
11b80 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11b90 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
11ba0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
11bb0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11bc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11bd0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11be0 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11bf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11c00 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11c10 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11c20 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11c30 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11c40 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11c50 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
11c60 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
11c70 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11c80 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
11c90 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
11ca0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11cb0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11cc0 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11cd0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11ce0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11cf0 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11d00 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11d10 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11d20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11d30 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11d40 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11d50 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11d60 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
11d70 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11d80 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
11d90 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
11da0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
11db0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11dc0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11dd0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11de0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11df0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11e00 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11e10 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11e20 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11e30 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11e40 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11e50 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11e60 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11e70 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11e80 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
11e90 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
11ea0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
11eb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11ec0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11ed0 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11ee0 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11ef0 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11f00 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11f10 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11f20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11f30 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11f40 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11f60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11f70 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11f90 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
11fa0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
11fb0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11fc0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11fd0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11ff0 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
12000 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
12010 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
12020 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
12030 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
12050 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
12060 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
12070 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12080 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
12090 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
120a0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
120b0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
120c0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
120d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
120e0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
120f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
12100 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
12110 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
12120 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
12130 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
12140 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
12150 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
12160 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
12170 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
12180 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
12190 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
121a0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
121b0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
121c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
121d0 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
121e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
121f0 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
12200 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
12210 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
12220 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
12230 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
12240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12250 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
12260 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
12270 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
12280 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
12290 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
122a0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
122b0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
122c0 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51  * failure..*/.SQ
122d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
122e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
122f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
12300 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
12310 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
12320 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ALL sqlite3_shut
12330 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
12340 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12350 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
12360 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
12370 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12380 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
12390 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
123a0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
123b0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
123c0 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
123d0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
123e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
123f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
12400 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
12410 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
12420 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
12430 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
12440 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
12450 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
12460 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
12470 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
12480 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
12490 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
124a0 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
124b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
124c0 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
124d0 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
124e0 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
124f0 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
12500 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
12510 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
12520 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
12530 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74  .** <b>The sqlit
12540 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
12550 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
12560 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70  eadsafe. The app
12570 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
12580 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   ensure that no 
12590 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
125a0 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
125b0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
125c0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
125d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
125e0 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a  s running.</b>.*
125f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12600 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
12610 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ace.** may only 
12620 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
12630 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
12640 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
12650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
12660 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
12670 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
12680 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
12690 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
126a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
126b0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
126c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
126d0 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
126e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
126f0 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
12700 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
12710 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
12720 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
12730 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
12740 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
12750 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
12760 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
12770 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
12780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
12790 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
127a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
127b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
127c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
127d0 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
127e0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
127f0 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
12800 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
12810 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
12820 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
12830 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
12840 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
12850 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
12860 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
12870 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
12880 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
12890 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
128a0 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
128b0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
128c0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
128d0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
128e0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
128f0 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
12900 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
12910 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
12920 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
12930 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
12940 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
12950 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
12960 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
12970 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  nt SQLITE_CDECL 
12980 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
12990 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
129a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
129b0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
129c0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
129d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
129e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
129f0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
12a00 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
12a10 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
12a20 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12a30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
12a40 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
12a50 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
12a60 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
12a70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
12a80 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
12a90 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
12aa0 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
12ab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12ac0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
12ad0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12ae0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
12af0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
12b00 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12b10 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
12b20 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
12b30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12b40 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
12b50 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
12b60 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
12b70 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
12b80 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
12b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12ba0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
12bb0 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
12bc0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12bd0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
12be0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
12bf0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
12c00 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
12c10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
12c20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
12c30 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
12c40 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
12c50 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
12c60 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
12c70 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43  API int SQLITE_C
12c80 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62 5f  DECL sqlite3_db_
12c90 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
12ca0 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
12cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12cc0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
12cd0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
12ce0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
12cf0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
12d00 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
12d10 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
12d20 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
12d30 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12d40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
12d50 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
12d60 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
12d70 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
12d80 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12d90 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
12da0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12db0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
12dc0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
12dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12de0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
12df0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12e00 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
12e10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12e20 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
12e30 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
12e40 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
12e50 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
12e60 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
12e70 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
12e80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12e90 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
12ea0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
12eb0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
12ec0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
12ed0 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
12ee0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
12ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12f00 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
12f10 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
12f20 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
12f30 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
12f40 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
12f50 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
12f60 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
12f70 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
12f80 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
12f90 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
12fa0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
12fb0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
12fc0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
12fd0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
12fe0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
12ff0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
13000 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
13010 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
13020 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
13030 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
13040 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
13050 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
13060 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
13070 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
13080 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
13090 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
130a0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
130b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
130c0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
130d0 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
130e0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
130f0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
13100 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
13110 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
13120 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
13130 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
13140 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
13150 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
13160 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
13170 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
13180 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
13190 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
131a0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
131b0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
131c0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
131d0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
131e0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
131f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13200 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
13210 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
13220 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
13230 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
13240 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
13250 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
13260 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
13270 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
13280 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
13290 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
132a0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
132b0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
132c0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
132d0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
132e0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
132f0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
13300 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
13310 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
13320 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
13330 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
13340 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
13350 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
13360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13370 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
13380 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
13390 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
133a0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
133b0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
133c0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
133d0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
133e0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
133f0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
13400 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
13410 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
13420 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
13430 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
13440 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13450 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
13460 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
13470 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
13480 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
13490 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
134a0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
134b0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
134c0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
134d0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
134e0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
134f0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
13500 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
13510 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
13520 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
13530 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
13540 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
13550 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
13560 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
13570 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
13580 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
13590 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
135a0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
135b0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
135c0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
135d0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
135e0 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
135f0 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
13600 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
13610 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
13620 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
13630 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
13640 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
13650 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
13660 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
13670 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
13680 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
13690 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
136a0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
136b0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
136c0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
136d0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
136e0 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
136f0 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
13700 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
13710 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
13720 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
13730 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
13740 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
13750 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
13760 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
13770 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
13780 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
13790 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
137a0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
137b0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
137c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
137d0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
137e0 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
137f0 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
13800 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
13810 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
13820 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
13830 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
13840 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
13850 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
13860 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13870 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
13880 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
13890 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
138a0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
138b0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
138c0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
138d0 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
138e0 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
138f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
13900 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
13910 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
13920 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
13930 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
13940 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
13950 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
13960 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
13970 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
13980 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
13990 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
139a0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
139b0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
139c0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
139d0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
139e0 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
139f0 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
13a00 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
13a10 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
13a20 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
13a30 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
13a40 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
13a50 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
13a60 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
13a70 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
13a80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
13a90 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
13aa0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
13ab0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
13ac0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
13ad0 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
13ae0 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
13af0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
13b00 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
13b10 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13b20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
13b30 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
13b40 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
13b50 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
13b60 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
13b70 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
13b80 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
13b90 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
13ba0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
13bb0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
13bc0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
13bd0 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
13be0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13bf0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
13c00 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
13c10 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
13c20 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
13c30 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
13c40 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
13c50 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
13c60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13c70 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
13c80 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
13c90 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
13ca0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
13cb0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
13cc0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
13cd0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
13ce0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
13cf0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
13d00 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
13d10 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
13d20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
13d30 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
13d40 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
13d50 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
13d60 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
13d70 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
13d80 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
13d90 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
13da0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
13db0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
13dc0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
13dd0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
13de0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
13df0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
13e00 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
13e10 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
13e20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
13e30 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
13e40 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
13e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
13e60 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
13e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13e80 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
13e90 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13ea0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13eb0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
13ec0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13ed0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
13ee0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
13ef0 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
13f00 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13f10 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
13f20 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
13f30 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
13f40 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
13f50 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
13f60 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
13f70 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
13f80 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13f90 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13fa0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13fb0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13fc0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13fd0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13fe0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
13ff0 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
14000 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14010 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
14020 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
14030 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
14040 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
14050 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
14060 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
14070 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
14080 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
14090 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
140a0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
140b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
140c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
140e0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
140f0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14100 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
14110 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
14120 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
14130 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
14140 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
14150 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14160 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
14170 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
14180 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
14190 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
141a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
141b0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
141c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
141d0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
141e0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
141f0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
14200 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
14210 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
14220 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
14230 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14240 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
14250 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
14260 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
14270 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
14280 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
14290 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
142a0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
142b0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
142c0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
142d0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
142e0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
142f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
14300 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
14310 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14320 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14330 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14340 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14350 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14360 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14370 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
14380 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
14390 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
143a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
143b0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
143c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
143d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
143e0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
143f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
14410 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
14420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14430 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14440 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14450 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
14460 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
14470 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
14480 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
14490 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
144a0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
144b0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
144c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
144d0 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
144e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
144f0 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
14500 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
14510 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
14520 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
14530 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
14540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
14550 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
14560 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
14570 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
14580 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
14590 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
145a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
145b0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
145c0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
145d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
145e0 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
145f0 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
14600 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
14610 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
14620 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14630 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
14640 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
14650 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
14660 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
14670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
14680 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
14690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
146a0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
146b0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
146c0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
146d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
146e0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
146f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14700 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14710 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14720 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14730 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14740 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
14750 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
14760 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
14770 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
14780 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
14790 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
147a0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
147b0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
147c0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
147d0 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
147e0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
147f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14800 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
14810 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
14820 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
14830 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14840 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
14850 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14860 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14870 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
14880 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
14890 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
148a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
148b0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
148c0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
148d0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
148e0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
148f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14900 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
14910 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
14920 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
14930 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
14940 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14950 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
14960 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
14970 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
14980 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
14990 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
149a0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
149b0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
149c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
149d0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
149e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
149f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14a00 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
14a10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14a20 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
14a30 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14a40 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
14a50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14a60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14a70 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14a80 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14a90 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14aa0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14ab0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
14ac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
14ad0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
14ae0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14af0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14b00 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
14b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
14b20 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
14b30 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
14b40 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
14b50 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
14b60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
14b70 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14b80 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
14b90 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
14ba0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
14bb0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
14bc0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
14bd0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14c00 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
14c10 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
14c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14c30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c40 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
14c50 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
14c60 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
14c70 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
14c80 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
14c90 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
14ca0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
14cb0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
14cc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14cd0 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
14ce0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
14cf0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
14d00 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
14d10 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
14d20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
14d30 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
14d40 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
14d50 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
14d60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
14d70 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
14d80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
14d90 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
14da0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14db0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
14dc0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
14dd0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36  [sqlite3_status6
14de0 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  4()].**   </ul>)
14df0 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
14e00 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14e10 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
14e20 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
14e30 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
14e40 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
14e50 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
14e60 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
14e70 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
14e80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14e90 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
14ea0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
14eb0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14ec0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14ed0 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
14ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14ef0 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
14f00 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14f10 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f  IG_SCRATCH optio
14f20 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
14f30 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
14f40 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  er.** that SQLit
14f50 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63  e can use for sc
14f60 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e  ratch memory.  ^
14f70 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  (There are three
14f80 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
14f90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14fa0 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74  CRATCH:  A point
14fb0 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
14fc0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
14fd0 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
14fe0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
14ff0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
15000 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
15010 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
15020 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
15030 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
15040 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
15050 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
15060 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20  tions (N).)^.** 
15070 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15080 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
15090 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
150a0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
150b0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
150c0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
150d0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
150e0 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f   will not use mo
150f0 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
15100 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
15110 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69  thread..** ^SQLi
15120 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
15130 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20  quest a scratch 
15140 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
15150 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
15160 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
15170 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e   page size..** ^
15180 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
15190 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
151a0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
151b0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
151c0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
151d0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
151e0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
151f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
15200 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
15210 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
15220 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70  memory needed.<p
15230 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61  >.** ^When the a
15240 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69  pplication provi
15250 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f  des any amount o
15260 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  f scratch memory
15270 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45   using.** SQLITE
15280 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c  _CONFIG_SCRATCH,
15290 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75   SQLite avoids u
152a0 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65  nnecessary large
152b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
152c0 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74  loc|heap allocat
152d0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63  ions]..** This c
152e0 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20  an help [Robson 
152f0 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65  proof|prevent me
15300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15310 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f  failures] due to
15320 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e   heap.** fragmen
15330 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65  tation in low-me
15340 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79  mory embedded sy
15350 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  stems..** </dd>.
15360 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15370 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
15380 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15390 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
153a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
153c0 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
153d0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
153e0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
153f0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
15400 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
15410 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
15420 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
15430 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
15440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15450 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
15460 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
15470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
15480 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
15490 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
154a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
154b0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
154c0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
154d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a  ONFIG_PCACHE2].*
154e0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
154f0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72  option..** ^Ther
15500 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
15510 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
15520 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15530 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
15540 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
15550 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
15560 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
15570 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
15580 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
15590 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
155a0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
155b0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
155c0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
155d0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
155e0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
155f0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
15600 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
15610 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
15620 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
15630 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
15640 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
15650 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
15660 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
15670 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
15680 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
15690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
156a0 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e  HE_HDRSZ] option
156b0 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33   .** to [sqlite3
156c0 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e  _config()]..** ^
156d0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
156e0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
156f0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
15700 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
15710 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
15720 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
15730 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  y.  The first.**
15740 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
15750 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15760 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c  -byte aligned bl
15770 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68  ock of memory th
15780 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73  at.** is at leas
15790 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
157a0 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73  memory, otherwis
157b0 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  e subsequent beh
157c0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
157d0 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  fined..** ^SQLit
157e0 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
157f0 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
15800 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
15810 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
15820 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
15830 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
15840 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
15850 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
15860 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
15870 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
15880 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
15890 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
158a0 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
158b0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
158c0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
158d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
158e0 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
158f0 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
15900 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ce.</dd>.**.** [
15910 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
15920 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
15930 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
15940 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15960 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
15970 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
15980 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
15990 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
159a0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
159b0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
159c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
159d0 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
159e0 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
159f0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
15a00 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a  _SCRATCH] and.**
15a10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15a20 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
15a30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15a40 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
15a50 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15a60 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
15a70 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
15a80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
15a90 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
15aa0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
15ab0 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
15ac0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
15ad0 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
15ae0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
15af0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15b00 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
15b10 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
15b20 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
15b30 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
15b40 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
15b50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
15b60 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
15b70 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
15b80 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
15b90 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
15ba0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
15bb0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
15bc0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
15bd0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
15be0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
15bf0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
15c00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
15c10 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
15c20 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
15c30 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
15c40 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
15c50 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
15c60 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
15c70 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
15c80 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
15c90 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
15ca0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
15cb0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
15cc0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
15cd0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
15ce0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
15cf0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
15d00 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
15d10 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
15d20 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
15d30 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15d40 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
15d50 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
15d60 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
15d70 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
15d80 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
15d90 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
15da0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
15db0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
15dc0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
15dd0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
15de0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
15df0 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
15e00 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
15e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15e20 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
15e30 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
15e40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15e60 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
15e70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15e80 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
15e90 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
15ea0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
15eb0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15ec0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15ed0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
15ee0 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
15ef0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
15f00 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
15f10 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
15f20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
15f30 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
15f40 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
15f50 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
15f60 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
15f70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
15f80 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15f90 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15fa0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
15fb0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
15fc0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
15fd0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
15fe0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15ff0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
16000 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
16010 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
16020 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16030 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
16040 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
16050 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
16060 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
16070 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
16080 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
16090 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
160a0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
160b0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
160c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
160d0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
160e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
160f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16100 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16110 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
16120 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
16130 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
16140 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16150 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
16160 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16170 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
16180 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16190 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
161a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
161b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
161c0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
161d0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
161e0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
161f0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
16200 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
16210 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
16220 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
16230 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
16240 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
16250 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
16260 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
16270 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
16280 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
16290 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
162a0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
162b0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
162c0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
162d0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
162e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
162f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
16300 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
16310 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
16320 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
16330 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
16340 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
16350 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
16360 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
16370 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
16380 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
16390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
163a0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
163b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
163c0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
163d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
163e0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
163f0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
16400 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16410 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
16420 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16430 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
16440 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16450 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16460 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
16470 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
16480 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
16490 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
164a0 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
164b0 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
164c0 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
164d0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
164e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
164f0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
16500 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
16510 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
16520 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
16530 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16540 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
16550 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
16560 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
16570 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
16580 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
16590 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
165a0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
165b0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
165c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
165d0 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
165e0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
165f0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
16600 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
16610 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
16620 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
16630 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
16640 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
16650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16660 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
16670 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16680 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
16690 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
166a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
166b0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
166c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
166d0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
166e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
166f0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16700 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
16710 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
16720 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
16730 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
16740 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
16750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
16760 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
16770 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
16780 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16790 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
167a0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
167b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
167c0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
167d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
167e0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
167f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
16800 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16810 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
16820 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16830 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
16840 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
16850 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16860 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
16870 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
16880 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
16890 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
168a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
168b0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
168c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
168e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
168f0 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
16900 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
16910 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
16920 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
16930 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
16940 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
16950 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
16960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16970 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
16980 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
16990 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
169a0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
169b0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
169c0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
169d0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
169e0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
169f0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
16a00 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
16a10 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
16a20 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
16a30 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
16a40 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
16a50 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
16a60 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
16a70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
16a80 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
16a90 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
16aa0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
16ab0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
16ac0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
16ad0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
16ae0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16af0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16b00 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
16b10 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
16b20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
16b30 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
16b40 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16b50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
16b60 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
16b70 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
16b80 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
16b90 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
16ba0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
16bb0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
16bc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16bd0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
16be0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
16bf0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
16c00 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
16c10 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
16c20 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
16c30 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16c40 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
16c50 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
16c60 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
16c70 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
16c80 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
16c90 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
16ca0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
16cb0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
16cc0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
16cd0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
16ce0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
16cf0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
16d00 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
16d10 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
16d20 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
16d30 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
16d40 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
16d50 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
16d60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16d70 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
16d80 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
16d90 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
16da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16db0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
16dc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16dd0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
16de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16df0 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
16e00 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16e10 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
16e20 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
16e30 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
16e40 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
16e50 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
16e60 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
16e70 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
16e80 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16e90 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
16ea0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16eb0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
16ec0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
16ed0 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
16ee0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
16ef0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16f00 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
16f10 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
16f20 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
16f30 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
16f40 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
16f50 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
16f60 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
16f70 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16f80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
16f90 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
16fa0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
16fb0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
16fc0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
16fd0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
16fe0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
16ff0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
17000 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
17010 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
17020 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
17030 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
17040 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17050 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
17060 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
17070 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
17080 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
17090 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
170a0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
170b0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
170c0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
170d0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
170e0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
170f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
17100 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
17110 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
17120 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17130 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
17140 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
17150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17160 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17170 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
17180 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
17190 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
171a0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
171b0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
171c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
171d0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
171e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
171f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
17200 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
17210 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
17220 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
17230 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
17240 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
17250 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
17260 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
17270 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
17280 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17290 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
172a0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
172b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
172c0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
172d0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
172e0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
172f0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
17300 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
17310 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
17320 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
17330 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
17340 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
17350 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
17360 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
17370 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
17380 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
17390 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
173a0 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
173b0 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
173c0 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
173d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
173e0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
173f0 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
17400 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
17410 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
17420 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17430 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
17440 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
17450 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
17460 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17470 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
17480 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17490 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
174a0 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
174b0 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
174c0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
174d0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
174e0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
174f0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
17500 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
17510 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
17520 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
17530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17540 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
17550 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
17560 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
17570 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
17580 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
17590 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
175a0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
175b0 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
175c0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
175d0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
175e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
175f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
17600 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
17610 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
17620 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
17630 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
17640 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
17650 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
17660 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
17670 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
17680 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
17690 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
176a0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
176b0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
176c0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
176d0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
176e0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
176f0 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
17700 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
17710 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
17720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17730 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
17740 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17750 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
17760 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
17770 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
17780 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
17790 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
177a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
177b0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
177c0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
177d0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
177e0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
177f0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
17800 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
17810 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
17820 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
17830 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
17840 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
17850 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
17860 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
17870 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
17880 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17890 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
178a0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
178b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
178c0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
178d0 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
178e0 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
178f0 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
17900 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
17910 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
17920 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
17930 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
17940 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
17950 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
17960 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
17970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
17980 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
17990 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
179a0 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
179b0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
179c0 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
179d0 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
179e0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
179f0 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
17a00 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
17a10 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
17a20 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
17a30 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
17a40 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
17a50 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
17a60 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
17a70 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
17a80 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
17a90 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
17aa0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
17ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17ac0 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
17ad0 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
17ae0 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
17af0 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
17b00 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
17b10 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
17b20 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
17b30 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
17b40 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
17b50 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
17b60 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
17b70 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
17b80 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
17b90 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
17ba0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
17bb0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
17bc0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
17bd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
17be0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
17bf0 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
17c00 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
17c10 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
17c20 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
17c30 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
17c40 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
17c50 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
17c60 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
17c70 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17c80 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
17c90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17ca0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
17cb0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
17cc0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17cd0 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
17ce0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
17cf0 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
17d00 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
17d10 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
17d20 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
17d30 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
17d40 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
17d50 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
17d60 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17d70 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
17d80 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
17d90 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
17da0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
17db0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
17dc0 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
17dd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17de0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17df0 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
17e00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17e10 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
17e20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17e30 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
17e40 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17e50 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
17e60 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
17e70 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17e80 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
17e90 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
17ea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
17eb0 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
17ec0 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
17ed0 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
17ee0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17ef0 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
17f00 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
17f10 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
17f20 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
17f30 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
17f40 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
17f50 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
17f60 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
17f70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17f80 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
17f90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17fa0 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
17fb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17fc0 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
17fd0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
17fe0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
17ff0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
18000 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
18010 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
18020 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
18030 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
18040 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
18050 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
18060 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
18070 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
18080 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18090 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
180a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
180b0 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
180c0 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
180d0 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
180e0 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
180f0 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
18100 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
18110 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
18120 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
18130 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
18140 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
18150 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
18160 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
18170 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
18180 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
18190 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
181a0 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
181b0 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
181c0 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  e..** </dl>.*/.#
181d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
181e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
181f0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
18200 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18210 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
18220 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
18230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18240 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
18250 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
18260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18270 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
18280 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
18290 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
182a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
182b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
182c0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
182d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
182e0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
182f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
18300 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
18310 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
18320 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
18330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
18340 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
18350 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18360 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18380 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
18390 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
183a0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
183b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
183c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
183d0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
183e0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
183f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
18400 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
18410 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
18420 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
18430 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18440 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
18450 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18460 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
18470 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
18480 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
18490 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
184a0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
184b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
184c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
184d0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
184e0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
184f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18500 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
18510 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18520 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
18530 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
18540 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
18550 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18560 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
18570 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
18580 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
18590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
185a0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
185b0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
185c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
185d0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
185e0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
185f0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
18600 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18610 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
18620 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
18630 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
18640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18650 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
18660 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
18670 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18680 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18690 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
186a0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
186b0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
186c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
186d0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
186e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
186f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
18700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18710 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
18720 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
18730 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
18740 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18750 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
18760 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
18770 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
18780 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18790 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
187a0 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
187b0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
187c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
187d0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
187e0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
187f0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
18800 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
18810 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
18820 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
18830 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18840 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
18850 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
18860 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18870 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
18880 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
18890 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
188a0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
188b0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
188c0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
188d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
188e0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
188f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18900 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
18910 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
18920 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
18930 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
18940 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
18950 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
18960 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
18970 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
18980 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
18990 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
189a0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
189b0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
189c0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
189d0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
189e0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
189f0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
18a00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
18a10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
18a20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
18a30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18a40 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
18a50 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18a60 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
18a70 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
18a80 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
18a90 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
18aa0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
18ab0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
18ac0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
18ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18ae0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
18af0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
18b00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18b10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
18b20 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
18b30 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
18b40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
18b50 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
18b60 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
18b70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18b80 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
18b90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18ba0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
18bb0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
18bc0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
18bd0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
18be0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
18bf0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
18c00 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
18c10 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
18c20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
18c30 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
18c40 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
18c50 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
18c60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
18c70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
18c80 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
18c90 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
18ca0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
18cb0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
18cc0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
18cd0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
18ce0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
18cf0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
18d00 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
18d10 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
18d20 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
18d30 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
18d40 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
18d50 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
18d60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18d70 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
18d80 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
18d90 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
18da0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
18db0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
18dc0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
18dd0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
18de0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
18df0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
18e00 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
18e10 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
18e20 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
18e30 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
18e40 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
18e50 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
18e60 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
18e70 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
18e80 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
18e90 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
18ea0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
18eb0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
18ec0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
18ed0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
18ee0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
18ef0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
18f00 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
18f10 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
18f20 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
18f30 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
18f40 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
18f50 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
18f60 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
18f70 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
18f80 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
18f90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18fa0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18fb0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
18fc0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18fd0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
18fe0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
18ff0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
19000 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19010 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
19020 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19030 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19040 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19050 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19060 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19070 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19080 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
19090 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
190a0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
190b0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
190c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
190d0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
190e0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
190f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19100 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19110 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19120 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19130 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19140 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
19150 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
19160 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
19170 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19180 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19190 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
191a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
191b0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
191c0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
191d0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
191e0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
191f0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
19200 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
19210 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
19220 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19230 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19240 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19250 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
19260 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
19270 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
19280 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
19290 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
192a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
192b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
192c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
192d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
192e0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
192f0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
19300 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
19310 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
19320 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
19330 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19340 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19350 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19360 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19370 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19380 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19390 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
193a0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
193b0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
193c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
193d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
193e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
193f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
19400 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
19410 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
19420 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19430 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
19440 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
19450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19460 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
19470 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
19480 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
19490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
194a0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
194b0 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
194c0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
194d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
194e0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
194f0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
19500 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
19510 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
19520 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
19530 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
19540 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
19550 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19560 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19570 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19580 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
19590 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
195a0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
195b0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
195c0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
195d0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
195e0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
195f0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19600 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19610 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19620 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
19630 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
19640 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74  CALL sqlite3_ext
19650 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
19660 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
19670 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
19680 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
19690 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
196a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
196b0 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
196c0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
196d0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
196e0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
196f0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
19700 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
19710 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
19720 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
19730 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
19740 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
19750 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
19760 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
19770 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
19780 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
19790 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
197a0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
197b0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
197c0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
197d0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
197e0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
197f0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
19800 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
19810 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
19820 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
19830 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
19840 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
19850 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
19860 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
19870 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19880 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
19890 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
198a0 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
198b0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
198c0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
198d0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
198e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
198f0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
19900 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
19910 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
19920 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19930 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
19940 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
19950 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19960 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19970 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
19980 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
19990 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
199a0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
199b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
199c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
199d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
199e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
199f0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
19a00 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
19a10 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
19a20 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
19a30 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
19a40 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
19a50 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
19a60 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
19a70 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
19a80 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
19a90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
19aa0 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
19ab0 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
19ac0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
19ad0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
19ae0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
19af0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
19b00 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
19b10 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
19b20 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
19b30 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
19b40 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
19b50 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
19b60 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
19b70 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
19b80 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
19b90 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
19ba0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
19bb0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
19bc0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
19bd0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19be0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
19bf0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
19c00 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
19c10 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
19c20 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
19c30 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
19c40 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
19c50 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
19c60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19c70 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
19c80 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
19c90 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
19ca0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
19cb0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
19cc0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
19cd0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
19ce0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
19cf0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
19d00 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
19d10 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
19d20 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
19d30 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
19d40 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
19d50 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
19d60 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
19d70 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
19d80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
19d90 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
19da0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
19db0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
19dc0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
19dd0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
19de0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
19df0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
19e00 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
19e10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
19e20 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
19e30 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
19e40 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
19e50 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
19e60 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19e70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
19e80 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
19e90 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
19ea0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
19eb0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
19ec0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19ed0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
19ee0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
19ef0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
19f00 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
19f10 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
19f20 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
19f30 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
19f40 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
19f50 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
19f60 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19f70 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
19f80 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
19f90 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
19fa0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
19fb0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
19fc0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19fd0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
19fe0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
19ff0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1a000 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1a010 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1a020 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a030 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
1a040 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1a050 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1a060 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a070 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1a080 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1a090 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1a0a0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  fied, inserted o
1a0b0 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
1a0c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1a0d0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
1a0e0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a0f0 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
1a100 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  t on the databas
1a110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
1a120 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e  cified by the on
1a130 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ly parameter..**
1a140 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1a150 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1a160 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
1a170 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
1a180 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1a190 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
1a1a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  on..**.** ^Only 
1a1b0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72  changes made dir
1a1c0 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53  ectly by the INS
1a1d0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a1e0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a1f0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
1a200 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68  d - auxiliary ch
1a210 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1a220 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
1a230 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a  | triggers], .**
1a240 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1a250 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41  tions] or [REPLA
1a260 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
1a270 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f  esolution are no
1a280 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
1a290 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
1a2a0 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1a2b0 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20  ercepted by .** 
1a2c0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1a2d0 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46  ger | INSTEAD OF
1a2e0 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e   triggers] are n
1a2f0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65  ot counted. ^The
1a300 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72   value .** retur
1a310 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
1a320 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61  hanges() immedia
1a330 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e  tely after an IN
1a340 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a350 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
1a360 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69  ment run on a vi
1a370 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  ew is always zer
1a380 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  o. Only changes 
1a390 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a  made to real .**
1a3a0 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e   tables are coun
1a3b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67  ted..**.** Thing
1a3c0 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c  s are more compl
1a3d0 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71  icated if the sq
1a3e0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a3f0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65  function is.** e
1a400 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20  xecuted while a 
1a410 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a420 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73  is running. This
1a430 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74   may happen if t
1a440 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  he.** program us
1a450 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  es the [changes(
1a460 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c  ) SQL function],
1a470 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65   or if some othe
1a480 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  r callback.** fu
1a490 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73  nction invokes s
1a4a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a4b0 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e   directly. Essen
1a4c0 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c  tially:.** .** <
1a4d0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ul>.**   <li> ^(
1a4e0 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20  Before entering 
1a4f0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a500 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  m the value retu
1a510 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1a520 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65    sqlite3_change
1a530 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  s() function is 
1a540 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65  saved. After the
1a550 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1a560 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20   .**        has 
1a570 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72  finished, the or
1a580 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20  iginal value is 
1a590 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a  restored.)^.** .
1a5a0 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68  **   <li> ^(With
1a5b0 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  in a trigger pro
1a5c0 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54  gram each INSERT
1a5d0 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c  , UPDATE and DEL
1a5e0 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73  ETE .**        s
1a5f0 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68  tatement sets th
1a600 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a610 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
1a620 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1a630 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e   upon completion
1a640 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63   as normal. Of c
1a650 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75  ourse, this valu
1a660 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75  e will not inclu
1a670 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e  de .**        an
1a680 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72  y changes perfor
1a690 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67  med by sub-trigg
1a6a0 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69  ers, as the sqli
1a6b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1a6c0 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77  *        value w
1a6d0 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64  ill be saved and
1a6e0 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20   restored after 
1a6f0 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72  each sub-trigger
1a700 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c   has run.)^.** <
1a710 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69  /ul>.** .** ^Thi
1a720 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  s means that if 
1a730 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51  the changes() SQ
1a740 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73  L function (or s
1a750 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a  imilar) is used.
1a760 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
1a770 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a780 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1a790 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1a7a0 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75  ger, it .** retu
1a7b0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73  rns the value as
1a7c0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61   set when the ca
1a7d0 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  lling statement 
1a7e0 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e  began executing.
1a7f0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73  .** ^If it is us
1a800 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1a810 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73   or subsequent s
1a820 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69  uch statement wi
1a830 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a  thin a trigger .
1a840 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20  ** program, the 
1a850 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72  value returned r
1a860 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62  eflects the numb
1a870 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1a880 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70  ied by the .** p
1a890 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20  revious INSERT, 
1a8a0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1a8b0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a8c0 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  n the same trigg
1a8d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
1a8e0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
1a8f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
1a900 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1a910 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1a920 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1a930 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1a940 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1a950 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1a960 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
1a970 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
1a980 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a990 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
1a9a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a9b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1a9c0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1a9d0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
1a9e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1a9f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1aa00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1aa10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1aa20 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1aa30 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1aa40 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1aa50 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1aa60 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1aa70 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1aa80 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1aa90 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
1aaa0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
1aab0 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
1aac0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
1aad0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
1aae0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
1aaf0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1ab00 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
1ab10 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
1ab20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1ab30 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
1ab40 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
1ab50 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
1ab60 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
1ab70 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
1ab80 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1ab90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1aba0 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
1abb0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1abc0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1abd0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
1abe0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
1abf0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1ac00 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1ac10 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
1ac20 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
1ac30 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
1ac40 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
1ac50 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
1ac60 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1ac70 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
1ac80 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1ac90 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1aca0 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
1acb0 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
1acc0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1acd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1ace0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1acf0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1ad00 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1ad10 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1ad20 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1ad30 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1ad40 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1ad50 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1ad60 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1ad70 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1ad80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1ad90 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1ada0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1adb0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1adc0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1add0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1ade0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1adf0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1ae00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1ae10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1ae20 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1ae30 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1ae40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ae50 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1ae60 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1ae70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1ae80 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1ae90 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1aea0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1aeb0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1aec0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1aed0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1aee0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1aef0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1af00 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1af10 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1af20 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1af30 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1af40 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1af50 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1af60 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1af70 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1af80 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1af90 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1afa0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1afb0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1afc0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1afd0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1afe0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1aff0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1b000 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1b010 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1b020 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1b030 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1b040 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b050 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1b060 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1b070 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1b080 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1b090 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1b0a0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1b0b0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1b0c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1b0d0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1b0e0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1b0f0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1b100 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1b110 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1b120 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1b130 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1b140 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1b150 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1b160 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1b170 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1b180 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1b190 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1b1a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1b1b0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1b1c0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1b1d0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1b1e0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1b1f0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1b200 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1b210 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1b220 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1b230 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1b240 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1b250 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1b260 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1b270 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b280 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1b290 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1b2a0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1b2b0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1b2c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1b2d0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1b2e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1b2f0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1b300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b310 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1b320 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1b330 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b340 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1b350 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1b360 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1b370 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1b380 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1b390 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1b3a0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1b3b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1b3c0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1b3d0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1b3e0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1b3f0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1b400 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1b410 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1b420 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1b430 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1b440 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1b450 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1b460 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1b470 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1b480 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1b490 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1b4a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b4b0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1b4c0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1b4d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1b4e0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b4f0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b500 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b510 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1b520 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1b530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b540 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1b550 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b560 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1b570 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1b580 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1b590 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1b5a0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
1b5b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1b5c0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1b5d0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1b5e0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1b5f0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1b600 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1b610 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1b620 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1b630 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1b640 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1b650 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1b660 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1b670 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1b680 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1b690 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1b6a0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1b6b0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1b6c0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1b6d0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1b6e0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1b6f0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1b700 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1b710 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1b720 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1b730 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1b740 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1b750 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1b760 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1b770 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1b780 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1b790 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1b7a0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1b7b0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1b7c0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1b7d0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1b7e0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1b7f0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1b800 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1b810 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1b820 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1b830 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1b840 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1b850 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1b860 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1b870 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1b880 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1b890 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1b8a0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1b8b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1b8c0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1b8d0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1b8e0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1b8f0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1b900 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1b910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1b920 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1b930 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1b940 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1b950 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1b960 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1b970 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1b980 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1b990 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b9a0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1b9b0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1b9c0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1b9d0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1b9e0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1b9f0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1ba00 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1ba10 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1ba20 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1ba30 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1ba40 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1ba50 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1ba60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1ba70 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1ba80 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1ba90 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1baa0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1bab0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1bac0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1bad0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1bae0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1baf0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1bb00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1bb10 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1bb20 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1bb30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1bb40 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1bb50 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1bb60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1bb70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1bb80 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1bb90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1bba0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1bbb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1bbc0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1bbd0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1bbe0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1bbf0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1bc00 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1bc10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1bc20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1bc30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1bc40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1bc50 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1bc60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
1bc70 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1bc80 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1bc90 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1bca0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1bcb0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1bcc0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1bcd0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1bce0 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
1bcf0 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
1bd00 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
1bd10 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d  sy handler}.** M
1bd20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1bd30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1bd40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
1bd50 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
1bd60 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
1bd70 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
1bd80 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1bd90 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
1bda0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
1bdb0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1bdc0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
1bdd0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
1bde0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
1bdf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1be00 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
1be10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1be20 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
1be30 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
1be40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
1be50 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
1be60 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
1be70 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
1be80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1be90 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
1bea0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1beb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
1bec0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1bed0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
1bee0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
1bef0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1bf00 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1bf10 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1bf20 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1bf30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1bf40 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1bf50 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1bf60 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1bf70 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1bf80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1bf90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1bfa0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1bfb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1bfc0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1bfd0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1bfe0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1bff0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c000 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1c010 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1c020 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c030 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1c040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1c050 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1c060 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1c070 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1c080 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1c090 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1c0a0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1c0b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1c0c0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1c0d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1c0e0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1c0f0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1c100 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1c110 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1c120 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1c130 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1c140 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1c150 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1c160 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1c170 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1c180 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1c190 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1c1a0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1c1b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1c1c0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1c1d0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1c1e0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1c1f0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1c200 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1c210 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1c220 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1c230 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1c240 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1c250 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1c260 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1c270 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1c280 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1c290 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1c2a0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1c2b0 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1c2c0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1c2d0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1c2e0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1c2f0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1c300 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1c310 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1c320 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1c330 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1c340 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1c350 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1c360 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1c370 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1c380 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1c390 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1c3a0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1c3b0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1c3c0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1c3d0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1c3e0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1c3f0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1c400 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1c410 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1c420 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1c430 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c440 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1c450 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1c460 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1c470 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c480 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1c490 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1c4a0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1c4b0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1c4c0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1c4d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1c4e0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1c4f0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1c500 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1c510 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1c520 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1c530 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1c540 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1c550 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1c560 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1c570 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1c580 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1c590 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1c5a0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1c5b0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1c5c0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1c5d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c5e0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1c5f0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1c600 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1c610 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1c620 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1c630 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1c640 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1c650 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1c660 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1c670 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1c680 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1c690 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1c6a0 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1c6b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1c6c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1c6d0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1c6e0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1c6f0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1c700 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1c710 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1c720 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1c730 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1c740 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1c750 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1c760 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1c770 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1c780 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1c790 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1c7a0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1c7b0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1c7c0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1c7d0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1c7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1c7f0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1c800 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1c810 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1c820 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49  handler..*/.SQLI
1c830 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1c840 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1c850 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1c860 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1c870 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1c880 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c890 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1c8a0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1c8b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c8c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1c8d0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1c8e0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1c8f0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1c900 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1c910 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1c920 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1c930 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1c940 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1c950 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1c960 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1c970 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1c980 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1c990 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1c9a0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1c9b0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1c9c0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1c9d0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1c9e0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1c9f0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1ca00 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1ca10 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1ca20 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1ca30 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1ca40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1ca50 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1ca60 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1ca70 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1ca80 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1ca90 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1caa0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1cab0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1cac0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1cad0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1cae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1caf0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1cb00 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1cb10 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1cb20 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1cb30 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1cb40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1cb50 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1cb60 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1cb70 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1cb80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1cb90 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1cba0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1cbb0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1cbc0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
1cbd0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1cbe0 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  LL sqlite3_busy_
1cbf0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1cc00 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1cc10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1cc20 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1cc30 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1cc40 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1cc50 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1cc60 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1cc70 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1cc80 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1cc90 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1cca0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1ccb0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1ccc0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1ccd0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1cce0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1ccf0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1cd00 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1cd10 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1cd20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1cd30 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1cd40 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1cd50 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1cd60 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1cd70 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1cd80 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1cd90 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1cda0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1cdb0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1cdc0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1cdd0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1cde0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1cdf0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1ce00 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1ce10 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1ce20 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1ce30 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1ce40 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1ce50 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1ce60 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1ce70 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1ce80 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1ce90 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1cea0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1ceb0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1cec0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1ced0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1cee0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1cef0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1cf00 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1cf10 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1cf20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1cf30 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1cf40 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1cf50 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1cf60 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1cf70 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1cf80 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1cf90 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1cfa0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1cfb0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1cfc0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1cfd0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1cfe0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1cff0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1d000 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1d010 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1d020 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1d030 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1d040 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1d050 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1d060 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1d070 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1d080 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1d090 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1d0a0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1d0b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1d0c0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1d0d0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1d0e0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1d0f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d100 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1d110 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1d120 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d130 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1d140 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1d150 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1d160 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d170 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1d180 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1d190 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1d1a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d1b0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1d1c0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1d1d0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1d1e0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1d1f0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1d200 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1d210 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1d220 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1d230 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1d240 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1d250 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1d260 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1d270 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1d280 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1d290 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1d2a0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1d2b0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1d2c0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1d2d0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1d2e0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1d2f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1d300 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d310 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1d320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d330 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1d340 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1d350 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1d360 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1d370 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d380 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1d390 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d3a0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1d3b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1d3c0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1d3d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d3e0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1d3f0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1d400 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1d410 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1d420 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1d430 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1d440 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d450 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1d460 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1d470 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1d480 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1d490 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1d4a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1d4b0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1d4c0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1d4d0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1d4e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1d4f0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1d500 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1d510 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1d520 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1d530 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1d540 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1d550 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1d560 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1d570 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1d580 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1d590 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1d5a0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1d5b0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1d5c0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1d5d0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1d5e0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1d5f0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1d600 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d610 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1d620 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d630 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1d640 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1d650 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1d660 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1d670 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1d680 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1d690 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1d6a0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1d6b0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1d6c0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1d6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d6e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1d6f0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1d700 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1d710 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1d720 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1d730 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1d740 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1d750 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1d760 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1d770 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1d780 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1d790 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1d7a0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1d7b0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1d7c0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1d7d0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1d7e0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1d7f0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1d800 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1d810 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1d820 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1d830 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1d840 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1d850 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1d860 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1d870 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1d880 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1d890 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1d8a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1d8b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d8c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d8d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1d8e0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1d8f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1d900 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1d910 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1d920 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1d930 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1d940 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1d950 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1d960 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1d970 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1d980 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1d990 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1d9a0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1d9b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1d9c0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1d9d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1d9e0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1d9f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1da00 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1da10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1da20 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
1da30 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  L sqlite3_free_t
1da40 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1da50 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1da60 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1da70 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1da80 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1da90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1daa0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1dab0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1dac0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1dad0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1dae0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1daf0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1db00 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1db10 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1db20 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1db30 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1db40 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1db50 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1db60 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1db70 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1db80 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1db90 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1dba0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1dbb0 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1dbc0 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1dbd0 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1dbe0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1dbf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1dc00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1dc10 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1dc20 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1dc30 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1dc40 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1dc50 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1dc60 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1dc70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1dc80 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1dc90 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1dca0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1dcb0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1dcc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1dcd0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1dce0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1dcf0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1dd00 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1dd10 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1dd20 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1dd30 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1dd40 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1dd50 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1dd60 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1dd70 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1dd80 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1dd90 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1dda0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1ddb0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1ddc0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1ddd0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1dde0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1ddf0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1de00 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1de10 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1de20 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1de30 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1de40 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1de50 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1de60 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1de70 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1de80 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1de90 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1dea0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1deb0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1dec0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1ded0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1dee0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1def0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1df00 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1df10 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1df20 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1df30 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1df40 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1df50 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1df60 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1df70 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1df80 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1df90 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1dfa0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1dfb0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1dfc0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1dfd0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1dfe0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1dff0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1e000 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1e010 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1e020 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1e030 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1e040 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1e050 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1e060 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1e070 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1e080 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1e090 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1e0a0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1e0b0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1e0c0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1e0d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1e0e0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1e0f0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1e100 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1e110 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1e120 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1e130 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1e140 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1e150 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1e160 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1e170 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1e180 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e190 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1e1a0 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1e1b0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1e1c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e1d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1e1e0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1e1f0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1e200 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1e210 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1e220 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1e230 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1e240 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1e250 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1e260 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1e270 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1e280 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1e290 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1e2a0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1e2b0 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1e2c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1e2d0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1e2e0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1e2f0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1e300 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1e310 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1e320 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1e330 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1e340 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1e350 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1e360 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1e370 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1e380 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1e390 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1e3a0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1e3b0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1e3c0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1e3d0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1e3e0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1e3f0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1e400 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1e410 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1e420 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1e430 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1e440 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1e450 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1e460 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e470 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1e480 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1e490 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e4a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1e4b0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1e4c0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1e4d0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1e4e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e4f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e500 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e510 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1e520 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1e530 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1e540 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e550 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e560 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e570 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e580 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e590 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1e5a0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1e5b0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1e5c0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1e5d0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1e5e0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1e5f0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1e600 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1e610 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e620 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e630 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e640 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1e650 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1e660 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e670 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e680 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1e690 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1e6a0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1e6b0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1e6c0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1e6d0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1e6e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e6f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1e700 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1e710 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1e720 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1e730 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e740 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1e750 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1e760 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1e770 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1e780 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1e790 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1e7a0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1e7b0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e7c0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1e7d0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1e7e0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1e7f0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1e800 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1e810 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1e820 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1e830 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1e840 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1e850 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1e860 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1e870 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1e880 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1e890 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1e8a0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1e8b0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1e8c0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1e8d0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1e8e0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1e8f0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1e900 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e910 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e920 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e930 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e940 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1e950 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1e960 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1e970 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1e980 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1e990 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1e9a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e9b0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1e9c0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1e9d0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1e9e0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1e9f0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1ea00 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1ea10 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1ea20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ea30 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1ea40 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1ea50 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1ea60 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1ea70 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1ea80 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1ea90 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1eaa0 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1eab0 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1eac0 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1ead0 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1eae0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1eaf0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1eb00 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1eb10 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1eb20 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1eb30 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1eb40 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1eb50 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1eb60 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1eb70 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1eb80 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1eb90 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1eba0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1ebb0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1ebc0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1ebd0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1ebe0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1ebf0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1ec00 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1ec10 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1ec20 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1ec30 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1ec40 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
1ec50 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1ec60 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d  _CDECL sqlite3_m
1ec70 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1ec80 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1ec90 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1eca0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1ecb0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1ecc0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1ecd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1ece0 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73   *SQLITE_CDECL s
1ecf0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ed00 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1ed10 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1ed20 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1ed30 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1ed40 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1ed50 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1ed60 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1ed70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ed80 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1ed90 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1eda0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1edb0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1edc0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1edd0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1ede0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1edf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1ee00 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1ee10 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1ee20 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1ee30 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1ee40 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1ee50 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1ee60 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1ee70 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1ee80 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1ee90 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1eea0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1eeb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eec0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1eed0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1eee0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1eef0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1ef00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1ef10 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1ef20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1ef30 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1ef40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1ef50 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1ef60 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1ef70 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1ef80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1ef90 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1efa0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1efb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1efc0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1efd0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1efe0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1eff0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1f000 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1f010 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1f020 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1f030 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1f040 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f050 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1f060 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1f070 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1f080 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1f090 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1f0a0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1f0b0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1f0c0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1f0d0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1f0e0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1f0f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1f100 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f110 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1f120 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1f130 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1f140 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1f150 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1f160 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1f170 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1f180 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1f190 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1f1a0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1f1b0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1f1c0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1f1d0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1f1e0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1f1f0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1f200 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1f210 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1f220 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1f230 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1f240 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1f250 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1f260 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1f270 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1f280 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1f290 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1f2a0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1f2b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1f2c0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1f2d0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1f2e0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1f2f0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1f300 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1f310 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1f320 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1f330 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1f340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f350 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f360 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1f370 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1f380 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1f390 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1f3a0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1f3b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1f3c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f3d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f3e0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1f3f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1f400 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1f410 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1f420 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1f430 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1f440 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1f450 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1f460 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1f470 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1f480 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1f490 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1f4a0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1f4b0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1f4c0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1f4d0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1f4e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f4f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1f500 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1f510 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1f520 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1f530 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1f540 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1f550 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1f560 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1f570 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1f580 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1f590 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1f5a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1f5b0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1f5c0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1f5d0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1f5e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1f5f0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1f600 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1f610 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1f620 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1f630 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1f640 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1f650 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1f660 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1f670 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1f680 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1f690 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f6a0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1f6b0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1f6c0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1f6d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1f6e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1f6f0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f700 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1f710 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1f720 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1f730 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1f740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f750 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1f760 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1f770 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1f780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1f790 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1f7a0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1f7b0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1f7c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1f7d0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1f7e0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1f7f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f800 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1f810 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1f820 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1f830 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1f840 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1f850 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1f860 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1f870 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1f880 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1f890 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1f8a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1f8b0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1f8c0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1f8d0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1f8e0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1f8f0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1f900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1f910 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1f920 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1f930 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1f940 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1f950 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1f960 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1f970 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1f980 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1f990 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1f9a0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1f9b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1f9c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f9d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1f9e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1f9f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1fa00 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1fa10 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1fa20 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1fa30 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1fa40 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1fa50 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1fa60 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1fa70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1fa80 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1fa90 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1faa0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1fab0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1fac0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1fad0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1fae0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1faf0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1fb00 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1fb10 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1fb20 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1fb30 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1fb40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1fb50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1fb60 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1fb70 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1fb80 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1fb90 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1fba0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1fbb0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1fbc0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1fbd0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1fbe0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1fbf0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1fc00 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1fc10 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1fc20 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1fc30 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1fc40 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1fc50 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1fc60 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1fc70 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1fc80 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1fc90 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1fca0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1fcb0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1fcc0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1fcd0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1fce0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1fcf0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1fd00 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1fd10 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1fd20 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1fd30 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1fd40 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1fd50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1fd60 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1fd70 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1fd80 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1fd90 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1fda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1fdb0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1fdc0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1fdd0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1fde0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1fdf0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1fe00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1fe10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1fe20 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1fe30 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1fe40 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1fe50 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1fe60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1fe70 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1fe80 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1fe90 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1fea0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1feb0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1fec0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1fed0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1fee0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
1fef0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
1ff00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1ff10 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1ff20 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1ff30 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ff40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ff50 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
1ff60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1ff70 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1ff80 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  LL sqlite3_reall
1ff90 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1ffa0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1ffb0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1ffc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1ffd0 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  4(void*, sqlite3
1ffe0 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
1fff0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
20000 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
20010 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51  _free(void*);.SQ
20020 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
20030 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53  _uint64 SQLITE_S
20040 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
20050 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
20060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
20070 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
20080 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
20090 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
200a0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
200b0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
200c0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
200d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
200e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
200f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
20100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
20110 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
20120 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
20130 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
20140 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
20150 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
20160 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20170 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
20180 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
20190 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
201a0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
201b0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
201c0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
201d0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
201e0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
201f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20200 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
20210 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
20220 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
20230 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20240 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
20250 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
20260 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
20270 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
20280 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20290 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
202a0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
202b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
202c0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
202d0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
202e0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
202f0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
20300 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
20310 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
20320 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
20330 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
20340 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
20350 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
20360 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
20370 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
20380 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
20390 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
203a0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
203b0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
203c0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
203d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
203e0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
203f0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
20400 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
20410 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20420 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
20430 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
20440 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
20450 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
20460 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
20470 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
20480 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
20490 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
204a0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
204b0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
204c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
204d0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
204e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
204f0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
20500 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ALL sqlite3_memo
20510 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
20520 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
20530 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
20540 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
20550 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20560 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20570 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20580 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
20590 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
205a0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
205b0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
205c0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
205d0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
205e0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
205f0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
20600 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
20610 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
20620 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
20630 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
20640 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
20650 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
20660 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
20670 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
20680 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
20690 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
206a0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
206b0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
206c0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
206d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
206e0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
206f0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
20700 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
20710 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
20720 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
20730 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
20740 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20750 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
20760 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
20770 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
20780 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
20790 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
207a0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
207b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
207c0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
207d0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
207e0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
207f0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
20800 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
20810 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
20820 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20830 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
20840 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
20850 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
20860 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
20870 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
20880 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
20890 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
208a0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
208b0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
208c0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
208d0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
208e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
208f0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
20900 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
20910 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
20920 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
20930 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
20940 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
20950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20960 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
20970 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
20980 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
20990 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
209a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
209b0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
209c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
209d0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
209e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
209f0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
20a00 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
20a10 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20a20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20a30 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20a40 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
20a50 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
20a60 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
20a70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20a80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
20a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20aa0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
20ab0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
20ac0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
20ad0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
20ae0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
20af0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
20b00 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
20b10 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
20b20 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
20b30 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
20b40 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
20b50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20b60 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
20b70 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
20b80 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
20b90 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
20ba0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20bb0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
20bc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
20bd0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
20be0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
20bf0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
20c00 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
20c10 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
20c20 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
20c30 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
20c40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
20c50 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
20c60 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
20c70 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
20c80 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
20c90 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
20ca0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
20cb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20cc0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
20cd0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
20ce0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
20cf0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
20d00 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
20d10 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
20d20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20d30 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
20d40 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
20d50 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
20d60 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20d70 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20d80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
20d90 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
20da0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
20db0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
20dc0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
20dd0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
20de0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
20df0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20e00 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
20e10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20e20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
20e30 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
20e40 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
20e50 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
20e60 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20e70 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20e80 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
20e90 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
20ea0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
20eb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
20ec0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20ed0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20ee0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
20ef0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
20f00 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
20f10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20f20 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
20f30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
20f40 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
20f50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
20f60 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
20f70 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
20f80 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
20f90 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
20fa0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
20fb0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
20fc0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
20fd0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
20fe0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
20ff0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
21000 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
21010 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
21020 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
21030 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
21040 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
21050 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
21060 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
21070 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
21080 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
21090 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
210a0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
210b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
210c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
210d0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
210e0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
210f0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
21100 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
21110 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
21120 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
21130 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
21140 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
21150 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
21160 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
21170 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
21180 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
21190 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
211a0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
211b0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
211c0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
211d0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
211e0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
211f0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
21200 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
21210 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
21220 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
21230 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
21240 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
21250 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
21260 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
21270 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
21280 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
21290 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
212a0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
212b0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
212c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
212d0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
212e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
212f0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
21300 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
21310 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
21320 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
21330 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
21340 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
21350 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
21360 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
21370 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
21380 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
21390 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
213a0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
213b0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
213c0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
213d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
213e0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
213f0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
21400 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
21410 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
21420 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
21430 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
21440 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
21450 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
21460 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
21470 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
21480 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
21490 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
214a0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
214b0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
214c0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
214d0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
214e0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
214f0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
21500 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
21510 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
21520 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
21530 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
21540 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
21550 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
21560 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
21570 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
21580 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
21590 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
215a0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
215b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
215c0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
215d0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
215e0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
215f0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21600 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
21610 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
21620 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
21630 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
21640 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
21650 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
21660 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
21670 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
21680 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
21690 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
216a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
216b0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
216c0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
216d0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
216e0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
216f0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
21700 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
21710 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
21720 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
21730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
21740 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21750 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
21760 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
21770 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
21780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21790 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
217a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
217b0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
217c0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
217d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
217e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
217f0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21800 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21810 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
21820 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
21830 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
21840 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
21850 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
21860 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
21870 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
21880 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
21890 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
218a0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
218b0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
218c0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
218d0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
218e0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
218f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
21900 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
21910 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
21920 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21930 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
21940 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
21950 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21960 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
21970 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
21980 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
21990 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
219a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
219b0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
219c0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
219d0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
219e0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
219f0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
21a00 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
21a10 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
21a20 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
21a30 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
21a40 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
21a50 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
21a60 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
21a70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
21a80 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
21a90 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
21aa0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
21ab0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
21ac0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
21ad0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21ae0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
21af0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
21b00 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
21b10 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21b20 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
21b30 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
21b40 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
21b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21b60 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
21b70 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
21b80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21b90 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21ba0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21bb0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
21bc0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
21bd0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
21be0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
21bf0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
21c00 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
21c10 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
21c20 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
21c30 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
21c40 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
21c50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21c60 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
21c70 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
21c80 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
21c90 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
21ca0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
21cb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
21cc0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
21cd0 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
21ce0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
21cf0 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
21d00 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
21d10 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
21d20 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
21d30 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
21d40 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
21d50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
21d60 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
21d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21d80 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
21d90 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
21da0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
21db0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
21dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21dd0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
21de0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21df0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21e00 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
21e10 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
21e20 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
21e30 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
21e40 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
21e50 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
21e60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
21e70 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
21e80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
21e90 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21ea0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
21eb0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
21ec0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
21ed0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
21ee0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21ef0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21f00 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
21f10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21f20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
21f30 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
21f40 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
21f50 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
21f60 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
21f70 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
21f80 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
21f90 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
21fa0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21fb0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
21fc0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21fd0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
21fe0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21ff0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
22000 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
22010 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
22020 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22030 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
22040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22050 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
22060 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
22070 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
22080 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
22090 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
220a0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
220b0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
220c0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
220d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
220e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
220f0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
22100 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
22110 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
22120 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
22130 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
22140 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
22150 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
22160 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
22170 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
22180 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
22190 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
221a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
221b0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
221c0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
221d0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
221e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
221f0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
22200 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22210 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22230 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
22240 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
22250 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22260 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22280 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
22290 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
222a0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
222b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
222c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
222d0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
222e0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
222f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22300 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22320 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
22330 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
22340 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22350 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22370 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
22380 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
22390 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
223a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
223b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
223c0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
223d0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
223e0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
223f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22410 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
22420 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
22430 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22440 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
22460 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
22470 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
22480 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22490 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
224a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
224b0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
224c0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
224d0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
224e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
224f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22500 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
22510 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
22520 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22530 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22540 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22550 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
22560 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
22570 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22580 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22590 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
225a0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
225b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
225c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
225d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
225e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
225f0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
22600 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22610 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22630 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22640 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
22650 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22660 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22680 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
22690 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
226a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
226b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
226c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
226d0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
226e0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
226f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22700 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22720 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
22730 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
22740 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22750 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22770 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
22780 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
22790 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
227a0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
227b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227c0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
227d0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
227e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
227f0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22810 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
22820 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
22830 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
22840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22860 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
22870 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
22880 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
22890 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
228a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
228b0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
228c0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
228d0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
228e0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
228f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22900 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22910 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
22920 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
22930 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
22950 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
22960 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
22970 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
22980 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22990 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
229a0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
229b0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
229c0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
229d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
229e0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
229f0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22a00 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22a10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22a20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22a30 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
22a40 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
22a50 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22a60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22a70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22a80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22a90 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
22aa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22ab0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22ac0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22ad0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22ae0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22af0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22b00 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22b10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
22b30 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
22b40 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22b50 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
22b60 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
22b70 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
22b80 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
22b90 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22ba0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
22bb0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
22bc0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
22bd0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
22be0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
22bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c00 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
22c10 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
22c20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22c30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22c40 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
22c50 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
22c60 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
22c70 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
22c80 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
22c90 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
22ca0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
22cb0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
22cc0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
22cd0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
22ce0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
22cf0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
22d00 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
22d10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
22d20 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
22d30 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
22d40 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
22d50 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
22d60 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
22d70 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
22d80 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
22d90 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
22da0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22db0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22dc0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
22dd0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
22de0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
22df0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
22e00 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
22e10 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
22e20 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
22e30 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
22e40 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
22e50 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
22e60 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
22e70 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
22e80 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
22e90 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
22ea0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
22eb0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
22ec0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
22ed0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
22ee0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
22ef0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
22f00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
22f10 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
22f20 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
22f30 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
22f40 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
22f50 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
22f60 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
22f70 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
22f80 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
22f90 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
22fa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
22fb0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
22fc0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
22fd0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
22fe0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
22ff0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
23000 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
23010 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
23020 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
23030 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
23040 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
23050 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
23060 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
23070 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
23080 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
23090 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
230a0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
230b0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
230c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
230d0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
230e0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
230f0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
23100 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
23110 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
23120 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
23130 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
23140 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23150 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
23160 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
23170 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
23180 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
23190 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
231a0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
231b0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
231c0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
231d0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
231e0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
231f0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
23200 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23210 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
23220 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
23230 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
23240 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
23250 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
23260 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
23270 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
23280 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
23290 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c 49  ENTAL void *SQLI
232a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
232b0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
232c0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
232d0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
232e0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
232f0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
23300 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23310 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
23320 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
23330 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
23340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23350 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
23360 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
23370 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
23380 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
23390 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
233a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
233b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
233c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
233d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
233e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
233f0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
23400 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
23410 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
23420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
23430 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
23440 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
23450 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
23460 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
23470 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
23480 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
23490 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
234a0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
234b0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
234c0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
234d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
234e0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
234f0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
23500 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
23510 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
23520 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
23530 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
23540 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
23550 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
23560 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
23570 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
23580 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
23590 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
235a0 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
235b0 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
235c0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
235d0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
235e0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
235f0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
23600 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
23610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
23620 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
23630 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
23640 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
23650 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
23660 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
23670 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
23680 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23690 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
236a0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
236b0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
236c0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
236d0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
236e0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
236f0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
23700 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
23710 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
23720 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
23730 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
23740 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
23750 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
23760 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
23770 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
23780 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
23790 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
237a0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
237b0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
237c0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
237d0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
237e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
237f0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
23800 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
23810 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
23820 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
23830 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23850 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
23860 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
23870 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
23880 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
23890 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
238a0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
238b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
238c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
238d0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
238e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
238f0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
23900 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
23910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23920 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
23930 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
23940 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
23950 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23970 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23980 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23990 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
239a0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
239b0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
239c0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
239d0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
239e0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
239f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23a00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23a10 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23a20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23a30 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23a40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23a50 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23a70 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23a80 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23a90 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23aa0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23ab0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23ac0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23ad0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23ae0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23af0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23b00 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23b10 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
23b20 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
23b30 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
23b40 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
23b50 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
23b60 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
23b70 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23b80 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
23b90 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
23ba0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
23bb0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
23bc0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
23bd0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
23be0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
23bf0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
23c00 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
23c10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23c20 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
23c30 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
23c40 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
23c50 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
23c60 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
23c70 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
23c80 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
23c90 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
23ca0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
23cb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
23cc0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
23cd0 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
23ce0 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
23cf0 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
23d00 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
23d10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
23d20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
23d30 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
23d40 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
23d50 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
23d60 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
23d70 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
23d80 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
23d90 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
23da0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
23db0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
23dc0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
23dd0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
23de0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
23df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23e00 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
23e10 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
23e20 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
23e30 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
23e40 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
23e50 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
23e60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
23e70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
23e80 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
23e90 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
23ea0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
23eb0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
23ec0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
23ed0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
23ee0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
23ef0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
23f00 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
23f10 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
23f20 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
23f30 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
23f40 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
23f50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
23f60 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
23f70 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
23f80 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
23f90 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
23fa0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
23fb0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
23fc0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23fd0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
23fe0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
23ff0 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
24000 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
24010 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
24020 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
24030 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
24040 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24050 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24060 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24070 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24080 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24090 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
240a0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
240b0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
240c0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
240d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
240e0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
240f0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24100 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
24110 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
24120 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
24130 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
24140 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
24150 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
24160 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24170 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24180 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24190 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
241a0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
241b0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
241c0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
241d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
241e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
241f0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
24200 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
24210 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24220 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24230 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
24240 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
24250 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
24260 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24270 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24280 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24290 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
242a0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
242b0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
242c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
242d0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
242e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
242f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24300 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24310 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
24320 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
24330 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
24340 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
24350 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
24360 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24370 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24380 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24390 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
243a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
243b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
243c0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
243d0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
243e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
243f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
24400 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
24410 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
24420 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
24430 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
24440 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
24450 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
24460 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24470 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24480 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24490 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
244a0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
244b0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
244c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
244d0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
244e0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
244f0 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
24500 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
24510 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
24520 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
24530 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24540 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
24550 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24560 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24570 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24590 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
245a0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
245b0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
245c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
245d0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
245e0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
245f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
24600 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
24610 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
24620 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24630 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
24640 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24660 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24670 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24680 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24690 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
246a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
246b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
246c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
246d0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
246e0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
246f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
24700 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
24710 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24720 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24730 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
24740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24750 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24760 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24770 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24790 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
247a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
247b0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
247c0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
247d0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
247e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
247f0 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
24800 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
24810 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
24820 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
24830 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
24840 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24850 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24860 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24870 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24880 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24890 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
248a0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
248b0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
248c0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
248d0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
248e0 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
248f0 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
24900 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
24910 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24920 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
24930 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
24940 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24950 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24960 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24970 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24980 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24990 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
249a0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
249b0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
249c0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
249d0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
249e0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
249f0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24a00 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24a10 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24a20 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24a30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24a40 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24a50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24a60 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24a70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24a80 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24a90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24aa0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24ab0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24ac0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24ad0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24ae0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24af0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24b00 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24b10 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24b20 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24b30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24b40 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24b50 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24b60 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
24b70 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
24b80 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
24b90 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
24ba0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
24bb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24bc0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
24bd0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
24be0 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
24bf0 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
24c00 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
24c10 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
24c20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
24c30 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
24c40 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
24c50 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
24c60 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
24c70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
24c80 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
24c90 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
24ca0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
24cb0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
24cc0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
24cd0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
24ce0 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
24cf0 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
24d00 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
24d10 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
24d20 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
24d30 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
24d40 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
24d50 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
24d60 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
24d70 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
24d80 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
24d90 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
24da0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
24db0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
24dc0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24dd0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
24de0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
24df0 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
24e00 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
24e10 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
24e20 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
24e30 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
24e40 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
24e50 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
24e60 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
24e70 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
24e80 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
24e90 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
24ea0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
24eb0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
24ec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24ed0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
24ee0 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
24ef0 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
24f00 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
24f10 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
24f20 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
24f30 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
24f40 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
24f50 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
24f60 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
24f70 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
24f80 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
24f90 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
24fa0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
24fb0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
24fc0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
24fd0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24fe0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
24ff0 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
25000 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
25010 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
25020 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
25030 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
25040 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
25050 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
25060 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
25070 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
25080 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25090 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
250a0 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
250b0 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
250c0 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
250d0 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
250e0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
250f0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
25100 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
25110 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
25120 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
25130 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
25140 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
25150 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
25160 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
25170 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
25180 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
25190 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
251a0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
251b0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
251c0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
251d0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
251e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
251f0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
25200 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
25210 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
25220 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
25230 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
25240 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
25250 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
25260 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
25270 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
25280 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
25290 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
252a0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
252b0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
252c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
252d0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
252e0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
252f0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
25300 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
25310 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
25320 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
25330 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
25340 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
25350 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
25360 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25370 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25380 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
25390 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
253a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
253b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
253c0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
253d0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
253e0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
253f0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
25400 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
25410 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
25420 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
25430 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
25440 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
25450 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25460 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
25470 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
25480 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
25490 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
254a0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
254b0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
254c0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
254d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
254e0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
254f0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
25500 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
25510 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
25520 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25530 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
25540 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
25550 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
25560 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
25570 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
25580 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
25590 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
255a0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
255b0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
255c0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
255d0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
255e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
255f0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
25600 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25610 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
25620 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25630 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
25640 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
25650 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25660 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
25670 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
25680 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
25690 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
256a0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
256b0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
256c0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
256d0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
256e0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
256f0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
25700 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
25710 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
25720 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
25730 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25740 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25750 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
25760 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
25770 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
25780 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25790 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
257a0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
257b0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
257c0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
257d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
257e0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
257f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25800 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
25810 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
25820 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
25830 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25840 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
25850 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25860 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
25870 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
25880 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
25890 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
258a0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
258b0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
258c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
258d0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
258e0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
258f0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
25900 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
25910 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
25920 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
25930 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
25940 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25950 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25960 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25970 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25980 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
25990 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
259a0 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
259b0 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
259c0 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
259d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
259e0 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
259f0 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
25a00 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
25a10 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
25a20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
25a30 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
25a40 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
25a50 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25a60 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
25a70 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
25a80 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25a90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
25aa0 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
25ab0 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
25ac0 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
25ad0 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
25ae0 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
25af0 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
25b00 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
25b10 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
25b20 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
25b30 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
25b40 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
25b50 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
25b60 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
25b70 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
25b80 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
25b90 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
25ba0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
25bb0 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
25bc0 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
25bd0 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
25be0 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
25bf0 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
25c00 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
25c10 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
25c20 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
25c30 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
25c40 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
25c50 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
25c60 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
25c70 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
25c80 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
25c90 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
25ca0 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
25cb0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
25cc0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
25cd0 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
25ce0 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
25cf0 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
25d00 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
25d10 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
25d20 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25d30 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
25d40 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
25d50 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
25d60 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
25d70 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
25d80 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
25d90 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
25da0 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
25db0 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
25dc0 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
25dd0 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
25de0 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
25df0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
25e00 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
25e10 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
25e20 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
25e30 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
25e40 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
25e50 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
25e60 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
25e70 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
25e80 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
25e90 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
25ea0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
25eb0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
25ec0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
25ed0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
25ee0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
25ef0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
25f00 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
25f10 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
25f20 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
25f30 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
25f40 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
25f50 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
25f60 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
25f70 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
25f80 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
25f90 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
25fa0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
25fb0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
25fc0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
25fd0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
25fe0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
25ff0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
26000 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
26010 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26020 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
26030 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
26040 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
26050 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
26060 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26070 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
26080 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26090 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
260a0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
260b0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
260c0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
260d0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
260e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
260f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26100 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
26110 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
26120 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
26130 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
26140 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
26150 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
26160 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
26170 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
26180 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
26190 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
261a0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
261b0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
261c0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
261d0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
261e0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
261f0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
26200 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
26210 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
26220 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
26230 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
26240 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
26250 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
26260 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
26270 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
26280 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
26290 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
262a0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
262b0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
262c0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
262d0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
262e0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
262f0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
26300 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
26310 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
26320 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
26330 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
26340 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
26350 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
26360 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
26370 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
26380 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
26390 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
263a0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
263b0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
263c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
263d0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
263e0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
263f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
26400 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
26410 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
26420 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
26430 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
26440 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
26450 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
26460 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
26470 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
26480 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
26490 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
264a0 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
264b0 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
264c0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
264d0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
264e0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
264f0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
26500 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
26510 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
26520 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
26530 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
26540 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
26550 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26560 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
26570 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
26580 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
26590 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
265a0 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
265b0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
265c0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
265d0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
265e0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
265f0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
26600 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
26610 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
26620 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
26630 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
26640 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
26650 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
26660 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
26670 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
26680 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
26690 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
266a0 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
266b0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
266c0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
266d0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
266e0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
266f0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
26700 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
26710 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
26720 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
26730 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
26740 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
26750 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26760 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
26770 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
26780 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
26790 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
267a0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
267b0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
267c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
267d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
267e0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
267f0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
26800 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
26810 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
26820 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
26830 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
26840 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
26850 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26860 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
26870 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
26880 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
26890 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
268a0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
268b0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
268c0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
268d0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
268e0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
268f0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
26900 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
26910 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
26920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26930 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
26940 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
26950 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
26960 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
26970 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
26980 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
26990 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
269a0 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
269b0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
269c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
269d0 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  LL sqlite3_open(
269e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
269f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
26a00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26a10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
26a20 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
26a30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
26a40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
26a50 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
26a60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
26a70 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  L sqlite3_open16
26a80 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
26a90 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26aa0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26ab0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
26ac0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
26ad0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
26ae0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
26af0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26b00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
26b10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
26b20 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
26b30 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
26b40 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
26b50 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
26b60 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
26b70 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
26b80 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
26b90 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
26ba0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26bb0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
26bc0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
26bd0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
26be0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
26bf0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
26c00 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
26c10 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
26c20 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
26c30 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
26c40 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
26c50 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
26c60 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
26c70 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
26c80 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
26c90 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
26ca0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
26cb0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
26cc0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
26cd0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
26ce0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
26cf0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
26d00 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
26d10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26d20 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
26d30 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
26d40 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
26d50 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
26d60 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
26d70 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
26d80 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
26d90 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
26da0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
26db0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
26dc0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
26dd0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
26de0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
26df0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
26e00 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
26e10 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
26e20 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
26e30 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
26e40 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
26e50 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
26e60 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
26e70 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
26e80 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
26e90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
26ea0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
26eb0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26ec0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
26ed0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
26ee0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
26ef0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
26f00 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
26f10 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
26f20 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
26f30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
26f40 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
26f50 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
26f60 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
26f70 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
26f80 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
26f90 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
26fa0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
26fb0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
26fc0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
26fd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
26fe0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
26ff0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
27000 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
27010 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27020 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
27030 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
27040 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
27050 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
27060 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
27070 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
27080 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
27090 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
270a0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
270b0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
270c0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
270d0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
270e0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
270f0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
27100 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
27110 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
27120 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27130 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
27140 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
27150 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27160 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
27170 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
27180 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
27190 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
271a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
271b0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
271c0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
271d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
271e0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
271f0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
27200 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
27210 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
27220 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27230 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
27240 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
27250 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
27260 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
27270 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27280 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
27290 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
272a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
272b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
272c0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
272d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
272e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
272f0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
27300 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
27310 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27320 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
27330 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
27340 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
27350 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
27360 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27370 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
27380 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
27390 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
273a0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
273b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
273c0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
273d0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
273e0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
273f0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
27400 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27410 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
27420 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
27430 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
27440 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
27450 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
27460 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
27470 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
27480 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75  TDCALL sqlite3_u
27490 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
274a0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
274b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
274c0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
274d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
274e0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
274f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
27500 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
27510 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
27520 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
27530 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
27540 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
27550 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
27560 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
27570 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
27580 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
27590 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
275a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
275b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
275c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
275d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
275e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
275f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
27600 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
27610 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
27620 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
27630 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
27640 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
27650 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
27660 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
27670 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
27680 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
27690 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
276a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
276b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
276c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
276d0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
276e0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
276f0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
27700 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
27710 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
27720 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27730 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
27740 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
27750 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
27760 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
27770 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
27780 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
27790 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
277a0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
277b0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
277c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
277d0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
277e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
277f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
27800 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
27810 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
27820 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
27830 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
27840 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
27850 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
27860 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
27870 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
27880 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
27890 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
278a0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
278b0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
278c0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
278d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
278e0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
278f0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
27900 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
27910 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
27920 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27930 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
27940 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
27950 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27960 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
27970 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
27980 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
27990 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
279a0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
279b0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
279c0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
279d0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
279e0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
279f0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
27a00 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
27a10 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
27a20 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
27a30 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
27a40 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
27a50 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
27a60 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
27a70 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
27a80 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
27a90 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
27aa0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
27ab0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
27ac0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
27ad0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
27ae0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
27af0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
27b00 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
27b10 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
27b20 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
27b30 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
27b40 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
27b50 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
27b60 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
27b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27b80 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
27b90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
27ba0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
27bb0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
27bc0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
27bd0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
27be0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
27bf0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
27c00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
27c10 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
27c20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
27c30 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
27c40 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
27c50 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
27c60 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
27c70 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
27c80 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
27c90 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
27ca0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
27cb0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
27cc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
27cd0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
27ce0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
27cf0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
27d00 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
27d10 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
27d20 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
27d30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 63  ALL sqlite3_errc
27d40 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
27d50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27d60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
27d70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
27d80 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
27d90 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
27da0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
27db0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27dc0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
27dd0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
27de0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
27df0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27e00 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
27e10 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
27e20 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
27e30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
27e40 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
27e50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27e60 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
27e70 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
27e80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
27e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
27ea0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
27eb0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
27ec0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
27ed0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
27ee0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
27ef0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
27f00 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
27f10 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
27f20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
27f30 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
27f40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
27f50 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
27f60 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
27f70 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
27f80 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
27f90 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
27fa0 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
27fb0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
27fc0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
27fd0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
27fe0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
27ff0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
28000 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
28010 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
28020 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
28030 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
28040 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
28050 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
28060 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
28070 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
28080 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
28090 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
280a0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
280b0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
280c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
280d0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
280e0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
280f0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
28100 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
28110 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
28120 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
28130 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
28140 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
28150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28160 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28170 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
28180 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
28190 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
281a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
281b0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
281c0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
281d0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
281e0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
281f0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
28200 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
28210 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28220 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
28230 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28240 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
28250 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
28260 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
28270 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
28280 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
28290 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
282a0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
282b0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
282c0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
282d0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
282e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
282f0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
28300 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
28310 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28320 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28330 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
28340 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
28350 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
28360 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
28370 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
28380 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
28390 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
283a0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
283b0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
283c0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
283d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
283e0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
283f0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
28400 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28410 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28420 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28430 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28440 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28450 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28460 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
28470 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
28480 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
28490 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
284a0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
284b0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
284c0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
284d0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
284e0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
284f0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
28500 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
28510 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
28520 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
28530 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
28540 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
28550 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
28560 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
28570 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
28580 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
28590 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
285a0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
285b0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
285c0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
285d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
285e0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
285f0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
28600 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
28610 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28620 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
28630 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
28640 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
28650 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
28660 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
28670 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
28680 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
28690 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
286a0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
286b0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
286c0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
286d0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
286e0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
286f0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
28700 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
28710 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
28720 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
28730 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
28740 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
28750 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
28760 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
28770 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
28780 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
28790 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
287a0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
287b0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
287c0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
287d0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
287e0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
287f0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
28800 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
28810 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
28820 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
28830 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
28840 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28850 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
28860 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
28870 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
28880 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
28890 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
288a0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
288b0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
288c0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
288d0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
288e0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
288f0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
28900 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
28910 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
28920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
28930 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
28940 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
28950 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
28960 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
28970 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
28980 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
28990 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
289a0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
289b0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
289c0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
289d0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
289e0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
289f0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
28a00 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
28a10 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
28a20 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
28a30 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28a40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28a50 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
28a60 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
28a70 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
28a80 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
28a90 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
28aa0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
28ab0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
28ac0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
28ad0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
28ae0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
28af0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
28b00 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
28b10 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
28b20 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
28b30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
28b40 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
28b50 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
28b60 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
28b70 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
28b80 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
28b90 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
28ba0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
28bb0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
28bc0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
28bd0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
28be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28bf0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
28c00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
28c10 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
28c20 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
28c30 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
28c40 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
28c50 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
28c60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28c70 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
28c80 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
28c90 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
28ca0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
28cb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
28cc0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
28cd0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
28ce0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
28cf0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
28d00 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
28d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
28d20 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
28d30 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28d40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
28d50 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
28d60 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
28d70 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
28d80 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
28d90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28da0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
28db0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
28dc0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
28dd0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
28de0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
28df0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
28e00 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
28e10 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
28e20 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
28e30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
28e40 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
28e50 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
28e60 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
28e70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28e80 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
28e90 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
28ea0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
28eb0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
28ec0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28ed0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
28ee0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
28ef0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
28f00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28f10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
28f20 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
28f30 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
28f40 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
28f50 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
28f60 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
28f70 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
28f80 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
28f90 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
28fa0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
28fb0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
28fc0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
28fd0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
28fe0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
28ff0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
29000 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
29010 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
29020 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29030 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
29040 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
29050 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29060 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
29070 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29080 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
29090 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
290a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
290b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
290c0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
290d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
290e0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
290f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29100 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
29110 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
29120 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
29130 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29140 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29150 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
29160 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29170 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
29180 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
29190 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
291a0 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
291b0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
291c0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
291d0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
291e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
291f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
29200 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
29210 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
29220 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29230 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
29240 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
29250 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
29260 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
29270 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
29280 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
29290 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
292a0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
292b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
292c0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
292d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
292e0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
292f0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
29300 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
29310 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29320 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
29330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29340 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29350 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
29360 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
29370 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
29380 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
29390 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
293a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
293b0 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
293c0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
293d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
293e0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
293f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29400 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
29410 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29420 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
29430 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
29440 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
29450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29460 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
29470 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
29480 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29490 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
294a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
294b0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
294c0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
294d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
294e0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
294f0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
29500 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
29510 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
29520 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
29530 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
29540 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
29550 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
29560 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29570 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
29580 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
29590 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
295a0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
295b0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
295c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
295d0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
295e0 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
295f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29600 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29610 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
29620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
29630 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
29640 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
29650 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
29660 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
29670 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29680 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  e3.** CONSTRUCTO
29690 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
296a0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
296b0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
296c0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
296d0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
296e0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
296f0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
29700 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
29710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
29720 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
29730 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
29740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
29750 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
29760 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
29770 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29780 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
29790 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
297a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
297b0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
297c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
297d0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
297e0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
297f0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
29800 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
29810 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
29820 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
29830 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
29840 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
29850 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
29860 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
29870 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
29880 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
29890 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
298a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
298b0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
298c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
298d0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
298e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
298f0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
29900 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29910 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
29920 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
29930 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29940 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70  . ^If nByte is p
29950 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74  ositive, then it
29960 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29970 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20  r of bytes read 
29980 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20  from zSql.  ^If 
29990 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74  nByte is zero, t
299a0 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a  hen no prepared.
299b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ** statement is 
299c0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66  generated..** If
299d0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
299e0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  s that the suppl
299f0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
29a00 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
29a10 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61  en.** there is a
29a20 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e   small performan
29a30 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
29a40 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
29a50 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
29a60 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
29a70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
29a80 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
29a90 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
29aa0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
29ab0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ator..**.** ^If 
29ac0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
29ad0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
29ae0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
29af0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
29b00 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
29b10 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
29b20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
29b30 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
29b40 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
29b50 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
29b60 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
29b70 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
29b80 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
29b90 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
29ba0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
29bb0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
29bc0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
29bd0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
29be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29bf0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
29c00 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
29c10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29c20 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
29c30 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
29c40 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
29c50 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
29c60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
29c70 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
29c80 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
29c90 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
29ca0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
29cb0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
29cc0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
29cd0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
29ce0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
29cf0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
29d00 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
29d10 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
29d20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29d30 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
29d40 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
29d50 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
29d60 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
29d70 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
29d80 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
29d90 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
29da0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
29db0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
29dc0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
29dd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
29de0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
29df0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29e00 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
29e10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29e20 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
29e30 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
29e40 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
29e50 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
29e60 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
29e70 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
29e80 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
29e90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
29ea0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
29eb0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
29ec0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
29ed0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
29ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
29ef0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
29f00 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
29f10 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
29f20 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
29f30 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
29f40 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
29f50 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
29f60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
29f70 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
29f80 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
29f90 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
29fa0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
29fb0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
29fc0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
29fd0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
29fe0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
29ff0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
2a000 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
2a010 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
2a020 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
2a030 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2a040 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
2a050 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
2a060 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
2a070 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
2a080 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
2a090 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
2a0a0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
2a0b0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
2a0c0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
2a0d0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
2a0e0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
2a0f0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
2a100 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
2a110 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a120 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
2a130 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
2a140 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
2a150 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
2a160 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
2a170 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
2a180 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
2a190 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a1a0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
2a1b0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
2a1c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
2a1d0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
2a1e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
2a1f0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
2a200 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
2a210 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2a220 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
2a230 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
2a240 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
2a250 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
2a260 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
2a270 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
2a280 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
2a290 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
2a2a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
2a2b0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
2a2c0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a2d0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
2a2e0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
2a2f0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
2a300 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
2a310 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
2a320 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
2a330 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2a340 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
2a350 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
2a360 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
2a370 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
2a380 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
2a390 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
2a3a0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
2a3b0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
2a3c0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
2a3d0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
2a3e0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
2a3f0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
2a400 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2a410 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
2a420 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
2a430 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
2a440 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
2a450 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
2a460 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
2a470 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
2a480 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
2a490 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2a4a0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a4b0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
2a4c0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
2a4d0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
2a4e0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
2a4f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
2a500 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
2a510 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
2a520 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
2a530 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
2a540 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
2a550 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
2a560 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
2a570 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2a580 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2a590 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  L sqlite3_prepar
2a5a0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2a5b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2a5c0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2a5d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a5e0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2a5f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2a600 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2a610 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2a620 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2a630 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2a640 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2a650 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2a660 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2a670 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2a680 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a690 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2a6a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2a6b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2a6c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2a6d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a6e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2a6f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a700 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2a710 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2a720 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2a730 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a740 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2a750 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2a760 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2a770 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2a780 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2a790 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2a7a0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2a7b0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2a7c0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2a7d0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2a7e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a7f0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2a800 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2a810 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2a820 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2a830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a840 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2a850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a860 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2a870 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2a880 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2a890 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2a8a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2a8b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2a8c0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2a8d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2a8e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2a8f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2a900 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2a910 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2a920 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2a930 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2a940 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2a950 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2a960 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2a970 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2a980 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2a990 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a9a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2a9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a9c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2a9d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2a9e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2a9f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2aa00 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2aa10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2aa20 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2aa30 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2aa40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2aa50 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2aa60 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2aa70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2aa80 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2aa90 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2aaa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2aab0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2aac0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2aad0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2aae0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2aaf0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2ab00 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2ab10 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2ab20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ab30 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2ab40 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2ab50 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
2ab60 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
2ab70 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
2ab80 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2ab90 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
2aba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2abb0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
2abc0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
2abd0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
2abe0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2abf0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2ac00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ac10 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
2ac20 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2ac30 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ac40 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2ac50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ac60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac70 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
2ac80 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
2ac90 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
2aca0 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
2acb0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2acc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2acd0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
2ace0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2acf0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2ad00 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
2ad10 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
2ad20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
2ad30 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
2ad40 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
2ad50 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2ad60 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
2ad70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
2ad80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ad90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2ada0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
2adb0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
2adc0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2add0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
2ade0 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
2adf0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
2ae00 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
2ae10 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
2ae20 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
2ae30 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
2ae40 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
2ae50 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
2ae60 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
2ae70 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
2ae80 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2ae90 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
2aea0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
2aeb0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
2aec0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
2aed0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
2aee0 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
2aef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
2af00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
2af10 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
2af20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2af30 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
2af40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
2af50 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
2af60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2af70 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
2af80 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
2af90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
2afa0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
2afb0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
2afc0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
2afd0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
2afe0 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
2aff0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
2b000 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
2b010 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2b020 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
2b030 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
2b040 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
2b050 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
2b060 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2b070 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
2b080 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
2b090 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
2b0a0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
2b0b0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
2b0c0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
2b0d0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
2b0e0 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
2b0f0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
2b100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b110 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
2b120 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
2b130 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
2b140 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
2b150 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
2b160 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
2b170 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
2b180 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
2b190 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
2b1a0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2b1b0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
2b1c0 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   disk..*/.SQLITE
2b1d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b1e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b1f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
2b200 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b210 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b220 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2b230 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2b240 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
2b250 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
2b260 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b270 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b280 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
2b290 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b2a0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
2b2b0 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
2b2c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b2d0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
2b2e0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
2b2f0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2b300 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
2b310 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20  has neither run 
2b320 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72  to completion (r
2b330 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2b340 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73  TE_DONE] from [s
2b350 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29  qlite3_step(S)])
2b360 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73   nor.** been res
2b370 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
2b380 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
2b390 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b3a0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
2b3b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
2b3c0 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
2b3d0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
2b3e0 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
2b3f0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
2b400 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
2b410 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
2b420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2b430 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
2b440 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b450 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2b460 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
2b470 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
2b480 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2b490 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
2b4a0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
2b4b0 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
2b4c0 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
2b4d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
2b4e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
2b4f0 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
2b500 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
2b510 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
2b520 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
2b530 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
2b540 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
2b550 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
2b560 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
2b570 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
2b580 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
2b590 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
2b5a0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
2b5b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2b5c0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b5d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2b5e0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
2b5f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b600 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
2b610 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
2b620 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2b630 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b640 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
2b650 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b660 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
2b670 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
2b680 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2b690 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
2b6a0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
2b6b0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
2b6c0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
2b6d0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
2b6e0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
2b6f0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
2b700 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
2b710 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
2b720 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b730 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
2b740 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
2b750 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
2b760 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
2b770 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
2b780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2b790 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
2b7a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
2b7b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
2b7c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
2b7d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
2b7e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b7f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
2b800 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
2b810 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
2b820 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
2b830 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2b840 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
2b850 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
2b860 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
2b870 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
2b880 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
2b890 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
2b8a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
2b8b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b8c0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
2b8d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
2b8e0 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
2b8f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
2b900 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
2b910 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
2b920 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
2b930 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2b940 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
2b950 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
2b960 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
2b970 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
2b980 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
2b990 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
2b9a0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
2b9b0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
2b9c0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
2b9d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2b9e0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
2b9f0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
2ba00 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
2ba10 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2ba20 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
2ba30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2ba40 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
2ba50 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
2ba60 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
2ba70 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
2ba80 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
2ba90 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
2baa0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
2bab0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
2bac0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
2bad0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
2bae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2baf0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
2bb00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2bb10 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
2bb20 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
2bb30 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2bb40 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2bb50 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2bb60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2bb70 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
2bb80 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
2bb90 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
2bba0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
2bbb0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
2bbc0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
2bbd0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
2bbe0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
2bbf0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
2bc00 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2bc10 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2bc20 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2bc30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2bc40 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
2bc50 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
2bc60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2bc70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2bc80 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
2bc90 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
2bca0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
2bcb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2bcc0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2bcd0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2bce0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
2bcf0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
2bd00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2bd10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2bd20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2bd30 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
2bd40 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
2bd50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bd60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
2bd70 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2bd80 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
2bd90 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
2bda0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2bdb0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
2bdc0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2bdd0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2bde0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
2bdf0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
2be00 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
2be10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2be20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
2be30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2be40 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
2be50 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2be60 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2be70 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2be80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2be90 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2bea0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2beb0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2bec0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2bed0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2bee0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2bef0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2bf00 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2bf10 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2bf20 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2bf30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2bf40 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2bf50 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2bf60 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2bf70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2bf80 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2bf90 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2bfa0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2bfb0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2bfc0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2bfd0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2bfe0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2bff0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2c000 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2c010 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2c020 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2c030 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2c040 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2c050 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2c060 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2c070 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2c080 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2c090 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2c0a0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2c0b0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2c0c0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2c0d0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2c0e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2c0f0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2c100 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2c110 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2c120 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2c130 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2c140 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2c150 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2c160 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2c170 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c180 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2c190 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2c1a0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2c1b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c1c0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2c1d0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2c1e0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2c1f0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2c200 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2c210 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2c220 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2c230 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2c240 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2c250 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2c260 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2c270 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2c280 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2c290 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2c2a0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2c2b0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2c2c0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2c2d0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2c2e0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2c2f0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2c300 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2c310 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2c320 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2c330 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2c340 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2c350 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2c360 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2c370 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2c380 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2c390 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2c3a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2c3b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2c3c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2c3d0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2c3e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2c3f0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2c400 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2c410 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2c420 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2c430 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2c440 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2c450 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2c460 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2c470 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2c480 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2c490 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2c4a0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2c4b0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2c4c0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2c4d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2c4e0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2c4f0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2c500 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2c510 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2c520 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2c530 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2c540 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2c550 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2c560 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2c570 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2c580 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2c590 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c5a0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2c5b0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2c5c0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2c5d0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2c5e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2c5f0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2c600 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2c610 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2c620 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2c630 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2c640 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2c650 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2c660 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2c670 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2c680 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2c690 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2c6a0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2c6b0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2c6c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2c6d0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c6e0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2c6f0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2c700 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2c710 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2c720 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2c730 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2c740 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2c750 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2c760 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2c770 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2c780 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2c790 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2c7a0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2c7b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2c7c0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2c7d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2c7e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2c7f0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2c800 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2c810 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2c820 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2c830 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2c840 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2c850 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2c860 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2c870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2c880 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2c890 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2c8a0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2c8b0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2c8c0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2c8d0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2c8e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c8f0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2c900 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2c910 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2c920 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2c930 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2c940 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2c950 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2c960 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2c970 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2c980 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2c990 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2c9a0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2c9b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2c9c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2c9d0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2c9e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2c9f0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2ca00 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2ca10 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2ca20 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2ca30 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2ca40 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2ca50 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2ca60 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2ca70 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2ca80 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2ca90 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2caa0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2cab0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2cac0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2cad0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2cae0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2caf0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2cb00 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2cb10 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2cb20 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2cb30 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2cb40 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2cb50 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2cb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2cb70 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2cb80 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2cb90 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2cba0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2cbb0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2cbc0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2cbd0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2cbe0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2cbf0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2cc00 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2cc10 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2cc20 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2cc30 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2cc40 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2cc50 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2cc60 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2cc70 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2cc80 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2cc90 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2cca0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2ccb0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2ccc0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2ccd0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2cce0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2ccf0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2cd00 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2cd10 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2cd20 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2cd30 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2cd40 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2cd50 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2cd60 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2cd70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2cd80 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2cd90 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2cda0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2cdb0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2cdc0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2cdd0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2cde0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2cdf0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2ce00 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2ce10 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2ce20 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2ce30 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2ce40 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2ce50 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2ce60 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2ce70 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2ce80 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2ce90 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2cea0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2ceb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2cec0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2ced0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2cee0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2cef0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2cf00 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2cf10 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2cf20 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2cf30 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2cf40 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2cf50 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2cf60 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2cf70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cf80 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2cf90 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2cfa0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2cfb0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2cfc0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2cfd0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2cfe0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2cff0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2d000 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2d010 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2d020 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2d030 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2d040 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2d050 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2d060 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2d070 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2d080 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2d090 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2d0a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d0b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2d0c0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2d0d0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2d0e0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2d0f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2d100 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2d110 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2d120 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2d130 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2d140 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2d150 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2d160 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2d170 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2d180 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d190 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2d1a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2d1b0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2d1c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2d1d0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2d1e0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2d1f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d200 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2d210 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2d220 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d230 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2d240 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2d250 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2d260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d270 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2d280 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2d290 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2d2a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2d2b0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2d2c0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2d2d0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2d2e0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2d2f0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2d300 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2d310 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2d320 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2d330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d340 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2d350 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2d360 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2d370 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2d380 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2d390 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2d3a0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2d3b0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2d3c0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2d3d0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2d3e0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2d3f0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2d400 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2d410 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2d420 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2d430 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2d440 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2d450 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2d460 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2d470 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2d480 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2d490 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2d4a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2d4b0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2d4c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2d4d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2d4e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2d4f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2d500 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2d510 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2d520 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d530 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2d540 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2d550 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d560 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2d570 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d580 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2d590 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2d5a0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2d5b0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d5c0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2d5d0 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2d5e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2d5f0 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2d600 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2d610 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d620 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2d630 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d640 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d650 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2d660 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2d670 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2d680 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d690 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d6a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2d6b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d6c0 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
2d6d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d6e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d6f0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2d700 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d710 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2d720 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d730 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d740 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2d750 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d760 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d770 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2d780 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2d790 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2d7a0 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2d7b0 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2d7c0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2d7d0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2d7e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2d7f0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2d800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2d810 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2d820 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d840 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d860 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2d870 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2d880 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
2d890 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2d8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2d8b0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
2d8c0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
2d8d0 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ing);.SQLITE_API
2d8e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d8f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d900 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2d910 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d920 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2d930 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d940 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d950 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2d960 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2d970 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2d980 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d990 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2d9b0 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
2d9c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2d9d0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
2d9e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2d9f0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2da00 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
2da10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2da20 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2da30 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
2da40 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
2da50 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
2da60 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
2da70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da80 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
2da90 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
2daa0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
2dab0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
2dac0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
2dad0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
2dae0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
2daf0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
2db00 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
2db10 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
2db20 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
2db30 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
2db40 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
2db50 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
2db60 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
2db70 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2db80 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
2db90 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
2dba0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
2dbb0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
2dbc0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
2dbd0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
2dbe0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
2dbf0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
2dc00 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
2dc10 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
2dc20 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
2dc30 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
2dc40 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
2dc50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2dc60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2dc70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2dc80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2dc90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2dca0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2dcb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2dcc0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2dcd0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2dce0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2dcf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2dd00 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2dd10 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2dd20 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2dd30 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2dd40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2dd50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2dd60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2dd70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2dd80 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2dd90 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2dda0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2ddb0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2ddc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ddd0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2dde0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2ddf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2de00 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2de10 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2de20 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2de30 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2de40 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2de50 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2de60 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2de70 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2de80 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2de90 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2dea0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2deb0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2dec0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2ded0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2dee0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2def0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2df00 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2df10 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2df20 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2df30 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2df40 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2df50 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2df60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2df70 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2df80 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2df90 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2dfa0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2dfb0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2dfc0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2dfd0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2dfe0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2dff0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2e000 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2e010 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2e020 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2e030 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2e040 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2e050 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2e060 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2e070 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2e080 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2e090 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e0a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2e0b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e0c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e0d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e0e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e0f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e100 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2e110 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e120 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2e130 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
2e140 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2e150 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2e160 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e170 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2e180 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2e190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2e1a0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2e1b0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2e1c0 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2e1d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e1e0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2e1f0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2e200 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2e210 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2e220 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2e230 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2e240 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2e250 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2e260 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2e270 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2e280 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2e290 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2e2a0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2e2b0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2e2c0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2e2d0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2e2e0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2e2f0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2e300 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2e310 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2e320 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2e330 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2e340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e350 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2e360 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e370 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2e380 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2e390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e3a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2e3b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e3c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e3d0 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  ame()]..*/.SQLIT
2e3e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e3f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e400 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e410 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2e420 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2e430 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2e440 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2e450 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2e460 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2e470 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2e480 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e490 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2e4a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2e4b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2e4c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2e4d0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2e4e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2e4f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2e500 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e510 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2e520 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2e530 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2e540 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2e550 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2e560 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2e570 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65  CALL sqlite3_cle
2e580 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2e590 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2e5a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2e5b0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2e5c0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2e5d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e5e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2e5f0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2e600 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e610 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2e620 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2e630 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e640 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2e650 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2e660 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2e670 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2e680 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2e690 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2e6a0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2e6b0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2e6c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2e6d0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2e6e0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2e6f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2e700 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2e710 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e720 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e730 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2e740 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2e750 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
2e760 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e770 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2e780 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2e790 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2e7a0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2e7b0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2e7c0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2e7d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2e7e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2e7f0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2e800 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e810 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2e820 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2e830 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2e840 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e850 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2e860 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e870 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2e880 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2e890 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2e8a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2e8b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e8c0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2e8d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2e8e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2e8f0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2e900 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2e910 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2e920 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2e930 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2e940 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2e950 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2e960 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2e970 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2e980 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e990 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2e9a0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2e9b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2e9c0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2e9d0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2e9e0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2e9f0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2ea00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2ea10 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2ea20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2ea30 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2ea40 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2ea50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ea60 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2ea70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2ea80 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2ea90 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2eaa0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2eab0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2eac0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2ead0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2eae0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2eaf0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2eb00 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2eb10 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2eb20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2eb30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2eb40 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2eb50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2eb60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2eb70 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2eb80 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2eb90 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2eba0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2ebb0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2ebc0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2ebd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2ebe0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2ebf0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2ec00 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2ec10 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2ec20 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2ec30 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ec40 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2ec50 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2ec60 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2ec70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2ec80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2ec90 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2eca0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2ecb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2ecc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ecd0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2ece0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2ecf0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2ed00 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2ed10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ed20 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2ed30 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2ed40 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2ed50 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2ed60 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2ed70 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2ed80 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2ed90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2eda0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2edb0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2edc0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2edd0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2ede0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2edf0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2ee00 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2ee10 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2ee20 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2ee30 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2ee40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2ee50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2ee60 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2ee70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ee80 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2ee90 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2eea0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2eeb0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2eec0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2eed0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2eee0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2eef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ef00 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2ef10 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2ef20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2ef30 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2ef40 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2ef50 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2ef60 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2ef70 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2ef80 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2ef90 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2efa0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2efb0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2efc0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2efd0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2efe0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2eff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2f000 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2f010 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2f020 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2f030 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2f040 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2f050 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2f060 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2f070 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2f080 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2f090 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2f0a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2f0b0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2f0c0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2f0d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2f0e0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2f0f0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2f100 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2f110 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2f120 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2f130 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2f140 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2f150 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2f160 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2f170 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2f180 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2f190 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2f1a0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2f1b0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2f1c0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2f1d0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2f1e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2f1f0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2f200 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2f210 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2f220 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2f230 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2f240 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2f250 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2f260 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f270 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2f280 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2f290 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2f2a0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2f2b0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2f2c0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2f2d0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2f2e0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2f2f0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2f300 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2f310 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2f320 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2f330 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2f340 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2f350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2f360 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2f370 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f380 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f390 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f3a0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f3b0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f3c0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f3d0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2f3e0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f3f0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f400 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2f410 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2f420 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2f430 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2f440 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2f450 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2f460 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2f470 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f480 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2f490 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2f4a0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2f4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f4c0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2f4d0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2f4e0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2f4f0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2f500 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2f510 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2f520 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2f530 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2f540 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f550 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
2f560 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2f570 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2f580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2f590 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2f5a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2f5b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2f5c0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2f5d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2f5e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2f5f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f600 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2f610 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2f620 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2f630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2f640 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2f650 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2f660 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2f670 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2f680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f690 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2f6a0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2f6b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f6c0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2f6d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2f6e0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2f6f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f700 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2f710 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
2f720 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2f730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2f740 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2f750 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2f760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f770 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2f780 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2f790 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2f7a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2f7b0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2f7c0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2f7d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2f7e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2f7f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2f800 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2f810 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2f820 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2f830 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2f840 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2f850 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2f860 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2f870 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2f880 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2f890 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2f8a0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2f8b0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2f8c0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2f8d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2f8e0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2f8f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2f900 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2f910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2f920 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2f930 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2f940 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2f950 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2f960 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2f970 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2f980 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2f990 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2f9a0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2f9b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2f9c0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2f9d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2f9e0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2f9f0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2fa00 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2fa10 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2fa20 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2fa30 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2fa40 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2fa50 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2fa60 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2fa70 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2fa80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2fa90 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2faa0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2fab0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2fac0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2fad0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2fae0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2faf0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2fb00 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2fb10 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2fb20 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2fb30 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2fb40 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2fb50 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2fb60 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2fb70 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2fb80 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2fb90 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2fba0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2fbb0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2fbc0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2fbd0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2fbe0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2fbf0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2fc00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2fc10 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
2fc20 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2fc40 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2fc50 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2fc60 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51  I const void *SQ
2fc70 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2fc80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2fc90 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2fca0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2fcb0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2fcc0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2fcd0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2fce0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2fcf0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2fd00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fd10 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2fd20 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2fd30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2fd40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2fd50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2fd60 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2fd70 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2fd80 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2fd90 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2fda0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fdb0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2fdc0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2fdd0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2fde0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2fdf0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2fe00 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2fe10 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2fe20 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2fe30 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2fe40 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2fe50 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2fe60 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2fe70 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2fe80 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2fe90 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2fea0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2feb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2fec0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2fed0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2fee0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2fef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2ff00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2ff10 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2ff20 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2ff30 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2ff40 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2ff50 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2ff60 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2ff70 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2ff80 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2ff90 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2ffa0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2ffb0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2ffc0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2ffd0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2ffe0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2fff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
30000 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
30010 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
30020 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
30030 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
30040 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
30050 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
30060 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
30070 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
30080 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
30090 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
300a0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
300b0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
300c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
300d0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
300e0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
300f0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
30100 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
30110 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
30120 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
30130 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
30140 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
30150 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
30160 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30170 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
30180 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
30190 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
301a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
301b0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
301c0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
301d0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
301e0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
301f0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
30200 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
30210 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
30220 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
30230 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
30240 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
30250 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
30260 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
30270 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
30280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
30290 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
302a0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
302b0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
302c0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
302d0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
302e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
302f0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
30300 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
30310 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
30320 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
30330 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
30340 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
30350 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
30360 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
30370 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
30380 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
30390 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
303a0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
303b0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
303c0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
303d0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
303e0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
303f0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
30400 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
30410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
30420 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
30430 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
30440 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
30450 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
30460 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
30470 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
30480 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
30490 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
304a0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
304b0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
304c0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
304d0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
304e0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
304f0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
30500 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
30510 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
30520 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
30530 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
30540 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
30550 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
30560 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
30570 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
30580 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
30590 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
305a0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
305b0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
305c0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
305d0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
305e0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
305f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30600 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
30610 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
30620 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
30630 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
30640 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
30650 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
30660 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
30670 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30680 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30690 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
306a0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
306b0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
306c0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
306d0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
306e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
306f0 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
30700 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
30710 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
30720 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
30730 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
30740 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
30750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
30760 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
30770 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
30780 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
30790 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
307a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
307b0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
307c0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
307d0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
307e0 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
307f0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
30800 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
30810 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
30820 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
30830 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
30840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
30850 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
30860 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
30870 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
30880 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
30890 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
308a0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
308b0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
308c0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
308d0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
308e0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
308f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
30900 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
30910 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
30920 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
30930 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
30940 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
30950 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
30960 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
30970 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
30980 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
30990 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
309a0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
309b0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
309c0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
309d0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
309e0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
309f0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
30a00 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
30a10 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
30a20 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
30a30 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
30a40 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
30a50 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
30a60 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
30a70 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
30a80 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
30a90 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
30aa0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
30ab0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
30ac0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
30ad0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
30ae0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
30af0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
30b00 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
30b10 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
30b20 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
30b30 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
30b40 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
30b50 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
30b60 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
30b70 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
30b80 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
30b90 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
30ba0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
30bb0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
30bc0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
30bd0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
30be0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30bf0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
30c00 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
30c10 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
30c20 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
30c30 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
30c40 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
30c50 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
30c60 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
30c70 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
30c80 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
30c90 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
30ca0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
30cb0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
30cc0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
30cd0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
30ce0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
30cf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
30d00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30d10 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
30d20 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
30d30 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
30d40 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
30d50 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
30d60 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
30d70 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
30d80 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
30d90 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
30da0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
30db0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
30dc0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
30dd0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
30de0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
30df0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
30e00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
30e10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
30e20 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
30e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
30e40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
30e50 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
30e60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
30e70 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30e80 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
30e90 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
30ea0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
30eb0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
30ec0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
30ed0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
30ee0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
30ef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30f00 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
30f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
30f20 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
30f30 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
30f40 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
30f50 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
30f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
30f70 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
30f80 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
30f90 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
30fa0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30fb0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
30fc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
30fd0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
30fe0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
30ff0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
31000 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
31010 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
31020 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
31030 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
31040 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
31050 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31060 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
31070 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
31080 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31090 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
310a0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
310b0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
310c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
310d0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
310e0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
310f0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
31100 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
31110 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
31120 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
31130 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
31140 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
31150 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
31160 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
31170 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
31180 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
31190 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
311a0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
311b0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
311c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
311d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
311e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
311f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31200 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31210 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
31220 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
31230 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
31240 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
31250 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
31260 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
31270 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
31280 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
31290 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
312a0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
312b0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
312c0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
312d0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
312e0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
312f0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
31300 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
31310 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
31320 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
31330 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
31340 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
31350 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
31360 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
31370 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
31380 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
31390 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
313a0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
313b0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
313c0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
313d0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
313e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
313f0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
31400 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
31410 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
31420 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
31430 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
31440 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
31450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31460 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
31470 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
31480 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
31490 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
314a0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
314b0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
314c0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
314d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
314e0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
314f0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
31500 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
31510 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
31520 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
31530 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
31540 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
31550 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
31560 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31570 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
31580 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31590 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
315a0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
315b0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
315c0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
315d0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
315e0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
315f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
31600 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
31610 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
31620 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
31630 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
31640 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
31650 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
31660 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
31670 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
31680 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
31690 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
316a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
316b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
316c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
316d0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
316e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
316f0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
31700 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
31710 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
31720 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
31730 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
31740 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
31750 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
31760 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
31770 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
31780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31790 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
317a0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
317b0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
317c0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
317d0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
317e0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
317f0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
31800 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
31810 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
31820 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31830 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
31840 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
31850 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31860 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
31870 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
31880 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
31890 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
318a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
318b0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
318c0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
318d0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
318e0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
318f0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
31900 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
31910 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
31920 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
31930 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31940 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
31950 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
31960 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
31970 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
31980 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
31990 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
319a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
319b0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
319c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
319d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
319e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
319f0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
31a00 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
31a10 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
31a20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
31a30 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
31a40 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
31a50 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
31a60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
31a80 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
31a90 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
31aa0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
31ab0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
31ac0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
31ad0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
31ae0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
31af0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
31b00 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
31b10 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
31b20 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
31b30 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
31b40 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
31b50 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
31b60 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
31b70 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
31b80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
31b90 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
31ba0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
31bb0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
31bc0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
31bd0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
31be0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
31bf0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
31c00 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
31c10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
31c20 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
31c30 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
31c40 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
31c50 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
31c60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
31c70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31c80 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
31c90 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
31ca0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
31cb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31cc0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
31cd0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
31ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31cf0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
31d00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
31d10 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
31d20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
31d30 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
31d40 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
31d50 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
31d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31d70 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
31d80 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
31d90 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
31da0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
31db0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
31dc0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
31dd0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
31de0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
31df0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
31e00 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
31e10 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
31e20 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
31e30 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
31e40 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
31e50 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
31e60 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
31e70 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31e80 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
31e90 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31ea0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
31eb0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
31ec0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
31ed0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
31ee0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
31ef0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
31f00 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
31f10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31f30 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
31f40 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
31f50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31f60 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
31f70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
31f80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
31f90 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
31fa0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
31fb0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
31fc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31fd0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
31fe0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
31ff0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
32000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32010 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
32020 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
32030 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
32040 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
32050 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
32060 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
32070 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32080 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
32090 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
320a0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
320b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
320c0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
320d0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
320e0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
320f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32100 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
32110 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
32120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32130 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
32140 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
32150 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
32160 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
32170 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
32180 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
32190 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
321a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
321b0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
321c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
321d0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
321e0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
321f0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
32200 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
32210 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
32220 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
32230 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32240 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
32250 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32260 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
32270 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
32280 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
32290 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
322a0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
322b0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
322c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
322d0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
322e0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
322f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
32300 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
32310 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
32320 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
32330 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
32340 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
32350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32360 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
32370 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
32380 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
32390 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
323a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
323b0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
323c0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
323d0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
323e0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
323f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32400 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
32410 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
32420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32430 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
32440 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
32450 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
32460 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
32470 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
32480 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
32490 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
324a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
324b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
324c0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
324d0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
324e0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
324f0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
32500 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
32510 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32520 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
32530 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
32540 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
32550 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
32560 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
32570 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
32580 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
32590 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
325a0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
325b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
325c0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
325d0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
325e0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
325f0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
32600 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
32610 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
32620 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
32630 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
32640 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
32650 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
32660 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
32670 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
32680 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
32690 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
326a0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
326b0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
326c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
326d0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
326e0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
326f0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
32700 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
32710 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
32720 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
32730 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
32740 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
32750 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
32760 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
32770 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
32780 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
32790 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
327a0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
327b0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
327c0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
327d0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
327e0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
327f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
32800 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32810 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
32820 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
32830 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
32840 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
32850 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
32860 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
32870 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
32880 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
32890 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
328a0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
328b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
328c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
328d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
328e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
328f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
32900 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
32910 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
32920 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
32930 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
32940 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
32950 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32960 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
32970 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
32980 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
32990 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
329a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
329b0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
329c0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
329d0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
329e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
329f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
32a00 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
32a10 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
32a20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
32a30 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32a40 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
32a50 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
32a60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
32a70 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
32a80 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
32a90 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
32aa0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
32ab0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
32ac0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
32ad0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
32ae0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
32af0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
32b00 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
32b10 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
32b20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
32b30 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
32b40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32b50 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
32b60 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
32b70 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
32b80 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
32b90 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
32ba0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
32bb0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
32bc0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
32bd0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
32be0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
32bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32c00 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
32c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32c20 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
32c30 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
32c40 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
32c50 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
32c60 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
32c70 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
32c80 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
32c90 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
32ca0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
32cb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32cc0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
32cd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
32ce0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
32cf0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
32d00 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
32d10 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
32d20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
32d30 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
32d40 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
32d50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
32d60 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
32d70 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
32d80 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
32d90 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
32da0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
32db0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
32dc0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
32dd0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
32de0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
32df0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
32e00 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
32e10 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
32e20 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
32e30 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
32e40 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
32e50 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
32e60 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
32e70 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
32e80 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
32e90 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
32ea0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
32eb0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
32ec0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
32ed0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
32ee0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
32ef0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
32f00 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
32f10 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
32f20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
32f30 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
32f40 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
32f50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
32f60 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
32f70 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
32f80 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
32f90 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
32fa0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
32fb0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
32fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
32fd0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
32fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32ff0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
33000 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33010 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
33020 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33030 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
33040 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
33050 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
33060 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
33080 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
33090 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
330a0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
330b0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
330c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
330d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
330e0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
330f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33100 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
33110 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
33120 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
33130 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
33140 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
33150 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
33160 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
33170 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
33180 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
33190 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
331a0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
331b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
331c0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
331d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
331e0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
331f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
33200 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
33210 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
33220 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
33230 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
33240 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
33250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
33260 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
33270 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
33280 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
33290 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
332a0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
332b0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
332c0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
332d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
332e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
332f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
33300 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
33310 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
33320 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
33330 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
33340 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
33350 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
33360 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
33370 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
33380 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33390 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
333a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
333b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
333c0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
333d0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
333e0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
333f0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
33400 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
33410 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
33420 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
33430 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
33440 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
33450 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
33460 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
33470 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
33480 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
33490 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
334a0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
334b0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
334c0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
334d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
334e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
334f0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
33500 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
33510 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
33520 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
33530 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33550 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
33560 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
33570 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
33580 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33590 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
335a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
335b0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
335c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
335d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
335e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
335f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33600 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33610 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45  PI double SQLITE
33620 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33630 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
33640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33650 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33660 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
33670 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33680 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
33690 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
336a0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
336b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
336c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
336d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
336e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
336f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33700 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
33710 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54  gned char *SQLIT
33720 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33730 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
33740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33750 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33760 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
33770 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33790 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
337a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
337b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
337c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
337d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
337e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
337f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33800 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
33810 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ue *SQLITE_STDCA
33820 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33830 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
33840 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33850 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33860 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
33870 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
33880 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
33890 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
338a0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
338b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
338c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
338d0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
338e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
338f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
33900 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
33910 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
33920 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
33930 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
33940 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
33950 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
33960 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
33970 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
33980 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
33990 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
339a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
339b0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
339c0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
339d0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
339e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
339f0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
33a00 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
33a10 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
33a20 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
33a30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33a40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33a50 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
33a60 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
33a70 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
33a80 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
33a90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33aa0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
33ab0 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
33ac0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
33ad0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
33ae0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
33af0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33b00 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
33b10 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
33b20 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
33b30 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
33b40 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
33b50 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
33b60 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
33b70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
33b80 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
33b90 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
33ba0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
33bb0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
33bc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
33bd0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
33be0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
33bf0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
33c00 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
33c10 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
33c20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
33c30 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
33c40 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
33c50 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
33c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33c70 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
33c80 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
33c90 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
33ca0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
33cb0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
33cc0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
33cd0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
33ce0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
33cf0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
33d00 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
33d10 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
33d20 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
33d30 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
33d40 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
33d50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
33d60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d80 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
33d90 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
33da0 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
33db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33dc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33dd0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
33de0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
33df0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
33e00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
33e10 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
33e20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
33e30 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
33e40 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
33e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
33e60 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
33e70 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
33e80 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
33e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
33ea0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
33eb0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
33ec0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
33ed0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
33ee0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
33ef0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
33f00 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
33f10 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
33f20 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
33f30 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
33f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33f50 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
33f60 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
33f70 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
33f80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
33f90 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
33fa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
33fb0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
33fc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33fd0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
33fe0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
33ff0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
34000 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
34010 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
34020 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
34030 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
34040 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
34050 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
34060 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
34070 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
34080 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
34090 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
340a0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
340b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
340c0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
340d0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
340e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
340f0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
34100 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
34110 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
34120 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
34130 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
34140 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
34150 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
34160 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
34170 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
34180 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
34190 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
341a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
341b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
341c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
341d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
341e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
341f0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
34200 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
34210 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
34220 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
34230 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
34240 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34250 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
34270 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
34280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
342a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
342b0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
342c0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
342d0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
342e0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
342f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
34300 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
34310 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
34320 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
34330 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
34340 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
34350 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
34360 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
34370 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
34380 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
34390 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
343a0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
343b0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
343c0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
343d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
343e0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
343f0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
34400 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
34410 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
34420 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
34430 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
34440 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
34450 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34460 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
34470 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34480 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
34490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
344a0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
344b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
344c0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
344d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
344e0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
344f0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
34500 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
34510 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34520 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
34530 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
34540 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
34550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
34560 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34570 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
34580 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
34590 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
345a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
345b0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
345c0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
345d0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
345e0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
345f0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
34600 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
34610 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
34620 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
34630 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
34640 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
34650 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
34660 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
34670 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
34680 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
34690 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
346a0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
346b0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
346c0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
346d0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
346e0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
346f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
34700 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
34710 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
34720 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
34730 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
34740 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34750 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
34760 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
34770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
34780 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
34790 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
347a0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
347b0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
347c0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
347d0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
347e0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
347f0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
34800 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
34810 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
34820 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
34830 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
34840 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
34850 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
34860 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
34870 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34880 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
34890 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
348a0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
348b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
348c0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
348d0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
348e0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
348f0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
34900 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
34910 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
34920 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
34930 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
34940 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
34950 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
34960 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
34970 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34980 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
34990 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
349a0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
349b0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
349c0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
349d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
349e0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
349f0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
34a00 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
34a10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34a20 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
34a30 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
34a40 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
34a50 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
34a60 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
34a70 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
34a80 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
34a90 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
34aa0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
34ab0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
34ac0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
34ad0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
34ae0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
34af0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
34b00 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
34b10 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
34b20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
34b30 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
34b40 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
34b50 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
34b60 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
34b70 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
34b80 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
34b90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
34ba0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
34bb0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
34bc0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
34bd0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
34be0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
34bf0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
34c00 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
34c10 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
34c20 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
34c30 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
34c40 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
34c50 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
34c60 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
34c70 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
34c80 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
34c90 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
34ca0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
34cb0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
34cc0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
34cd0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
34ce0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
34cf0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
34d00 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
34d10 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
34d20 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
34d30 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
34d40 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
34d50 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
34d60 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
34d70 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
34d80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
34d90 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
34da0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
34db0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
34dc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
34dd0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
34de0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
34df0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
34e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
34e10 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
34e20 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
34e30 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
34e40 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
34e50 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
34e60 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
34e70 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
34e80 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
34e90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
34ea0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
34eb0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
34ec0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
34ed0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
34ee0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
34ef0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
34f00 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
34f10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
34f20 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
34f30 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
34f40 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
34f50 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
34f60 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
34f70 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
34f80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
34f90 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
34fa0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
34fb0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
34fc0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
34fd0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
34fe0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
34ff0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
35000 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
35010 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
35020 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
35030 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
35040 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
35050 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35060 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35070 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
35080 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
35090 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
350a0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
350b0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
350c0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
350d0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
350e0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
350f0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
35100 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
35110 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
35120 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
35130 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
35140 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
35150 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
35160 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
35170 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
35180 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35190 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
351a0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
351b0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
351c0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
351d0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
351e0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
351f0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
35200 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
35210 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
35220 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
35230 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
35240 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
35250 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35260 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35270 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
35280 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
35290 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
352a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
352b0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
352c0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
352d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
352e0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
352f0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
35300 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
35310 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
35320 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
35330 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
35340 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
35350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35360 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
35370 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
35380 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
35390 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
353a0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
353b0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
353c0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
353d0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
353e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
353f0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
35400 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
35410 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
35420 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
35430 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
35440 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
35450 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35460 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
35470 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
35480 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
35490 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
354a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
354b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
354c0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
354d0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
354e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
354f0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
35500 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
35510 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
35520 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
35530 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
35540 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
35550 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
35560 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
35570 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
35580 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
35590 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
355a0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
355b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
355c0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
355d0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
355e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
355f0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
35600 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
35610 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
35620 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
35630 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
35640 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
35650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35660 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
35670 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
35680 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
35690 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
356a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
356b0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
356c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
356d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65  CALL sqlite3_cre
356e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
356f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
35700 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
35710 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
35720 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
35730 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
35740 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
35750 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
35760 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
35770 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35780 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35790 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
357a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
357b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
357c0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
357d0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
357e0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
357f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
35800 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35810 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
35820 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
35830 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
35840 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
35850 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
35860 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
35870 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
35880 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35890 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
358a0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
358b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
358c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
358d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
358e0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
358f0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
35900 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
35910 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35920 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
35930 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
35940 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
35950 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
35960 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
35970 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
35980 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
35990 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
359a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
359b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
359c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
359d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
359e0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
359f0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35a00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
35a10 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
35a20 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
35a30 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
35a40 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
35a50 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
35a60 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
35a70 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
35a80 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
35a90 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
35aa0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
35ab0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
35ac0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
35ad0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
35ae0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
35af0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
35b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
35b10 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
35b20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
35b30 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
35b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
35b50 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
35b60 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
35b70 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
35b80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
35b90 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
35ba0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
35bb0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
35bc0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
35bd0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
35be0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
35bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
35c00 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
35c10 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
35c20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
35c30 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
35c40 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
35c50 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
35c60 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
35c70 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
35c80 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
35c90 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
35ca0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
35cb0 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
35cc0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
35cd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
35ce0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
35cf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35d00 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
35d10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
35d20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35d30 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
35d40 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
35d50 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
35d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
35d70 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
35d80 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
35d90 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
35da0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
35db0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
35dc0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
35dd0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
35de0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
35df0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
35e00 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
35e10 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
35e20 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
35e30 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
35e40 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
35e50 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
35e60 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
35e70 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
35e80 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
35e90 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
35ea0 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
35eb0 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
35ec0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
35ed0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
35ee0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
35ef0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
35f00 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
35f10 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
35f20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35f30 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
35f40 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
35f50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
35f60 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
35f70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
35f80 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
35f90 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
35fa0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
35fb0 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
35fc0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
35fd0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
35fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
35ff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36000 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
36010 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
36020 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36030 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
36040 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
36050 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
36060 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
36070 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36080 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
36090 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
360a0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
360b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
360c0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
360d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
360e0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
360f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
36100 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
36110 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
36120 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
36130 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
36140 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
36150 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
36160 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36170 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
36180 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
36190 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
361a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
361b0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
361c0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
361d0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
361e0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
361f0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
36200 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
36210 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
36220 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
36230 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
36240 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
36250 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
36260 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
36270 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36280 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36290 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
362a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
362b0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
362c0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
362d0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
362e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
362f0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
36300 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
36310 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
36320 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
36330 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
36340 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36350 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36360 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
36370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36380 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
36390 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
363a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
363b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
363c0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
363d0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
363e0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
363f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
36400 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
36410 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
36420 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
36430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36440 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
36450 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
36460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
36470 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
36480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
36490 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
364a0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
364b0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
364c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
364d0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
364e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
364f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
36500 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
36510 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
36520 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
36530 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
36540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36550 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
36560 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
36570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
36580 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
36590 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
365a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
365b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
365c0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
365d0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
365e0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
365f0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
36600 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
36610 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
36620 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
36630 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
36640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36650 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
36660 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
36670 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
36680 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
36690 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
366a0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
366b0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
366c0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
366d0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
366e0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
366f0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
36700 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
36710 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
36720 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
36730 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
36740 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
36750 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
36760 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
36770 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
36780 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
36790 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
367a0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
367b0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
367c0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
367d0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
367e0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
367f0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
36800 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
36810 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
36820 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
36830 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
36840 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
36850 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
36860 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
36870 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
36880 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
36890 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
368a0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
368b0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
368c0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
368d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
368e0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
368f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36900 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
36910 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36920 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
36930 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
36940 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
36950 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36960 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
36970 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
36980 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
36990 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
369a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
369b0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
369c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
369d0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
369e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
369f0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
36a00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
36a10 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
36a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
36a30 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
36a40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
36a50 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
36a60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36a70 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
36a80 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36a90 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
36aa0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36ab0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
36ac0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
36ad0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
36ae0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36af0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
36b00 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36b10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
36b20 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
36b30 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  LL sqlite3_value
36b40 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36b50 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
36b60 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
36b70 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
36b80 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
36b90 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36ba0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
36bb0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
36bc0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
36bd0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
36be0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36bf0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
36c00 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
36c10 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36c20 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
36c30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
36c40 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
36c50 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
36c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36c70 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
36c80 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
36c90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
36ca0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36cb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
36cc0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
36cd0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
36ce0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
36cf0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
36d10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36d20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36d30 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
36d50 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
36d60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
36d70 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
36d80 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
36d90 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
36da0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
36db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
36dc0 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
36dd0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
36de0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36df0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
36e00 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
36e10 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
36e20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
36e30 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
36e40 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
36e50 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
36e60 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
36e70 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
36e80 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
36e90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
36ea0 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
36eb0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
36ec0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
36ed0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
36ee0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
36ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
36f00 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
36f10 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
36f20 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
36f30 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
36f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
36f50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
36f60 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
36f70 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
36f80 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
36f90 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
36fa0 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
36fb0 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
36fc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
36fd0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
36fe0 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
36ff0 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  her..*/.SQLITE_A
37000 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  PI unsigned int 
37010 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
37020 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
37030 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
37040 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
37050 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
37060 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
37070 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37080 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
37090 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
370a0 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
370b0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
370c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
370d0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
370e0 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
370f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
37100 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
37110 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
37120 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
37130 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37140 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
37150 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
37160 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
37170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
37180 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
37190 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
371a0 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
371b0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
371c0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
371d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
371e0 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
371f0 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
37200 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
37210 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
37220 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
37230 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
37240 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
37250 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
37260 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
37270 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37280 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
37290 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
372a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
372b0 45 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65  ERIMENTAL sqlite
372c0 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f  3_value *SQLITE_
372d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
372e0 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20  value_dup(const 
372f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37300 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
37310 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
37320 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
37330 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37340 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76  e_free(sqlite3_v
37350 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
37360 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
37370 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
37380 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45  on Context.** ME
37390 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
373a0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
373b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
373c0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
373d0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
373e0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
373f0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
37400 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
37410 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
37420 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
37430 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37440 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37450 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
37460 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
37470 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
37480 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
37490 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
374a0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
374b0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
374c0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
374d0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
374e0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
374f0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
37500 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
37510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
37520 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
37530 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
37540 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
37550 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
37560 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
37570 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
37580 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37590 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
375a0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
375b0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
375c0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
375d0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
375e0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
375f0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
37600 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
37610 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
37620 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
37630 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
37640 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
37650 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
37660 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
37670 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
37680 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
37690 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
376a0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
376b0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
376c0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
376d0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
376e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
376f0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
37700 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
37710 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
37720 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
37730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37740 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37750 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
37760 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
37770 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
37780 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
37790 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
377a0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
377b0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
377c0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
377d0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
377e0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
377f0 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
37800 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
37810 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
37820 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
37830 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
37840 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
37850 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
37860 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
37870 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
37880 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
37890 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
378a0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
378b0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
378c0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
378d0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
378e0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
378f0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37900 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
37910 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
37920 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
37930 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
37940 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
37950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37960 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
37970 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
37980 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
37990 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
379a0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
379b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
379c0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
379d0 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
379e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
379f0 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
37a00 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
37a10 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
37a20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
37a30 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
37a40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
37a50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
37a60 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
37a70 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
37a80 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
37a90 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
37aa0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
37ab0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
37ac0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
37ad0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
37ae0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
37af0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
37b00 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
37b10 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
37b20 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
37b30 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
37b40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
37b50 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
37b60 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
37b70 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
37b80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37b90 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
37ba0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
37bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37bc0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
37bd0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
37be0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
37bf0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ntext.**.** ^The
37c00 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
37c10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
37c20 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
37c30 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
37c40 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
37c50 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
37c60 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
37c70 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
37c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37c90 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
37ca0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
37cb0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
37cc0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
37cd0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
37ce0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
37cf0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
37d00 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
37d10 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
37d20 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
37d30 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
37d40 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
37d50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37d60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
37d70 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
37d80 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
37d90 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37da0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
37db0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
37dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37dd0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
37de0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
37df0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
37e00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
37e10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37e20 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
37e30 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
37e40 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
37e50 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
37e60 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
37e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
37e80 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
37e90 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
37ea0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37eb0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
37ec0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37ed0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
37ee0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
37ef0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
37f00 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
37f10 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
37f20 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
37f30 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53 51 4c  API sqlite3 *SQL
37f40 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37f50 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
37f60 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
37f70 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
37f80 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
37f90 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
37fa0 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  a.** METHOD: sql
37fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
37fc0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
37fd0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
37fe0 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
37ff0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
38000 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
38010 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
38020 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
38030 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
38040 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
38050 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
38060 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
38070 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
38080 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
38090 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
380a0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
380b0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
380c0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
380d0 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
380e0 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
380f0 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
38100 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
38110 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
38120 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
38130 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
38140 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
38150 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
38160 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
38170 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
38180 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
38190 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
381a0 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
381b0 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
381c0 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
381d0 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
381e0 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
381f0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
38200 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
38210 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
38220 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
38230 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
38240 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
38250 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
38260 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
38270 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
38280 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
38290 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
382a0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
382b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
382c0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
382d0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
382e0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
382f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
38300 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
38310 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
38320 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
38330 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
38340 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
38350 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
38360 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
38370 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
38380 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
38390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
383a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
383b0 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
383c0 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
383d0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
383e0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
383f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38400 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
38410 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
38420 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
38430 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
38440 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
38450 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
38460 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
38470 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
38480 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
38490 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
384a0 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
384b0 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
384c0 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
384d0 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
384e0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
384f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
38500 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
38510 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
38520 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
38530 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
38540 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
38550 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
38560 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
38570 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
38580 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
38590 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
385a0 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
385b0 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
385c0 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
385d0 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
385e0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
385f0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
38600 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
38610 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
38620 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
38630 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
38640 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
38650 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
38660 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
38670 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
38680 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
38690 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
386a0 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
386b0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
386c0 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
386d0 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
386e0 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
386f0 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
38700 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
38710 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
38720 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
38730 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
38740 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
38750 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
38760 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
38770 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
38780 5f 7