System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 719f6891abcd9c459b5460b191d731cd12a3643e:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 38 2e 31 31 2e 20 20  ersion 3.8.11.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a  atic.#endif./***
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
0560: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74  n file sqliteInt
0570: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
05a0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
05b0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
05c0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
05d0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
05e0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
05f0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0600: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0610: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0620: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0630: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0640: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0650: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0660: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0670: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0680: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0690: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
06a0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
06b0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
06c0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69  **.** Internal i
0720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74  nterface definit
0730: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e  ions for SQLite.
0740: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f  .**.*/.#ifndef _
0750: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65  SQLITEINT_H_.#de
0760: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f  fine _SQLITEINT_
0770: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64  H_../*.** Includ
0780: 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  e the header fil
0790: 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f 6d  e used to custom
07a0: 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 72  ize the compiler
07b0: 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 56   options for MSV
07c0: 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 6c  C..** This shoul
07d0: 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 20  d be done first 
07e0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
07f0: 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 76  uccessfully prev
0800: 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a 20  ent spurious.** 
0810: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67  compiler warning
0820: 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 75  s due to subsequ
0830: 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 74  ent content in t
0840: 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 68  his file and oth
0850: 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 74  er files.** that
0860: 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 79   are included by
0870: 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f   this file..*/./
0880: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
0890: 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 6e  nclude msvc.h in
08a0: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
08b0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
08d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
08e0: 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e 68  egin file msvc.h
08f0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
0920: 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 72  *.** 2015 Januar
0930: 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  y 12.**.** The a
0940: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20  uthor disclaims 
0950: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69  copyright to thi
0960: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
0970: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61  In place of.** a
0980: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68   legal notice, h
0990: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e  ere is a blessin
09a0: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20  g:.**.**    May 
09b0: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20  you do good and 
09c0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20  not evil..**    
09d0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72  May you find for
09e0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75  giveness for you
09f0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76  rself and forgiv
0a00: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20  e others..**    
0a10: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72  May you share fr
0a20: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69  eely, never taki
0a30: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75  ng more than you
0a40: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a   give..**.******
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
0aa0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
0ab0: 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73  s code that is s
0ac0: 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 2e  pecific to MSVC.
0ad0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d 53 56  .*/.#ifndef _MSV
0ae0: 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 4d 53  C_H_.#define _MS
0af0: 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 69 6e  VC_H_..#if defin
0b00: 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 70 72  ed(_MSC_VER).#pr
0b10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b20: 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 70 72  able : 4054).#pr
0b30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b40: 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 70 72  able : 4055).#pr
0b50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b60: 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 70 72  able : 4100).#pr
0b70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0b80: 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 70 72  able : 4127).#pr
0b90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ba0: 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 70 72  able : 4130).#pr
0bb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0bc0: 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 70 72  able : 4152).#pr
0bd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0be0: 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 70 72  able : 4189).#pr
0bf0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c00: 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 70 72  able : 4206).#pr
0c10: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c20: 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 70 72  able : 4210).#pr
0c30: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c40: 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 70 72  able : 4232).#pr
0c50: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c60: 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 70 72  able : 4244).#pr
0c70: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0c80: 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 70 72  able : 4305).#pr
0c90: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ca0: 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 70 72  able : 4306).#pr
0cb0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0cc0: 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 70 72  able : 4702).#pr
0cd0: 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 69 73  agma warning(dis
0ce0: 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 65 6e  able : 4706).#en
0cf0: 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f  dif /* defined(_
0d00: 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 65 6e  MSC_VER) */..#en
0d10: 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 5f 20  dif /* _MSVC_H_ 
0d20: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */../***********
0d30: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e  *** End of msvc.
0d40: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **/./***********
0d80: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77  *** Continuing w
0d90: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66  here we left off
0da0: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   in sqliteInt.h 
0db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0dc0: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  **/../*.** Speci
0dd0: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57  al setup for VxW
0de0: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  orks.*/./*******
0df0: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
0e00: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65  vxworks.h in the
0e10: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0e20: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0e30: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
0e40: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
0e50: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a  le vxworks.h ***
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
0e90: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54  15-03-02.**.** T
0ea0: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
0eb0: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
0ec0: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
0ed0: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
0ee0: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
0ef0: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
0f00: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
0f10: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
0f20: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
0f30: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
0f40: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
0f50: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
0f60: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
0f70: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
0f80: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
0f90: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
0fa0: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
1000: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
1010: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20  tains code that 
1020: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57  is specific to W
1030: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f  ind River's VxWo
1040: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  rks.*/.#if defin
1050: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64  ed(__RTP__) || d
1060: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e  efined(_WRS_KERN
1070: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56  EL)./* This is V
1080: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20  xWorks.  Set up 
1090: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79  things specially
10a0: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a   for that OS.*/.
10b0: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b  #include <vxWork
10c0: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70  s.h>.#include <p
10d0: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d  thread.h>  /* am
10e0: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63  algamator: dontc
10f0: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ache */.#define 
1100: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65  OS_VXWORKS 1.#de
1110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f  fine SQLITE_OS_O
1120: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53  THER 0.#define S
1130: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f  QLITE_HOMEGROWN_
1140: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20  RECURSIVE_MUTEX 
1150: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1160: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e  _OMIT_LOAD_EXTEN
1170: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53  SION 1.#define S
1180: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43  QLITE_ENABLE_LOC
1190: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65  KING_STYLE 0.#de
11a0: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20  fine HAVE_UTIME 
11b0: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20  1.#else./* This 
11c0: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20  is not VxWorks. 
11d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
11e0: 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 20 2f  WORKS 0.#endif /
11f0: 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b  * defined(_WRS_K
1200: 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a  ERNEL) */../****
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f  ********** End o
1220: 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a  f vxworks.h ****
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69  ********** Conti
1270: 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c  nuing where we l
1280: 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74  eft off in sqlit
1290: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a  *********/../*.*
12b0: 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e 65 73  * These #defines
12c0: 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e   should enable >
12d0: 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74  2GB file support
12e0: 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65   on POSIX if the
12f0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  .** underlying o
1300: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1310: 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66  supports it.  If
1320: 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a   the OS lacks.**
1330: 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70   large file supp
1340: 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f  ort, or if the O
1350: 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68  S is windows, th
1360: 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f  ese should be no
1370: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b  -ops..**.** Tick
1380: 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f  et #2739:  The _
1390: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
13a0: 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65   macro must appe
13b0: 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a  ar before any.**
13c0: 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65   system #include
13d0: 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20  s.  Hence, this 
13e0: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75  block of code mu
13f0: 73 74 20 62 65 20 74 68 65 20 76 65 72 79 20 66  st be the very f
1400: 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20  irst.** code in 
1410: 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73  all source files
1420: 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69  ..**.** Large fi
1430: 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62  le support can b
1440: 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  e disabled using
1450: 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49   the -DSQLITE_DI
1460: 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68  SABLE_LFS switch
1470: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  .** on the compi
1480: 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65  ler command line
1490: 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73  .  This is neces
14a0: 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 65 20  sary if you are 
14b0: 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20  compiling.** on 
14c0: 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65  a recent machine
14d0: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e   (ex: Red Hat 7.
14e0: 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20  2) but you want 
14f0: 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72  your code to wor
1500: 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72  k.** on an older
1510: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65   machine (ex: Re
1520: 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20  d Hat 6.0).  If 
1530: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52  you compile on R
1540: 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69  ed Hat 7.2.** wi
1550: 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f  thout this optio
1560: 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65  n, LFS is enable
1570: 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20  .  But LFS does 
1580: 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 68 65  not exist in the
1590: 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65   kernel.** in Re
15a0: 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68  d Hat 6.0, so th
15b0: 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72  e code won't wor
15c0: 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d  k.  Hence, for m
15d0: 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a  aximum binary.**
15e0: 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75   portability you
15f0: 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53   should omit LFS
1600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76  ..**.** The prev
1610: 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 20 77  ious paragraph w
1620: 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30  as written in 20
1630: 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 61 67  05.  (This parag
1640: 72 61 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a  raph is written.
1650: 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38  ** on 2008-11-28
1660: 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 20 61  .) These days, a
1670: 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73  ll Linux kernels
1680: 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66   support large f
1690: 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20  iles, so.** you 
16a0: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20  should probably 
16b0: 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65  leave LFS enable
16c0: 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62  d.  But some emb
16d0: 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20  edded platforms 
16e0: 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46  might.** lack LF
16f0: 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  S in which case 
1700: 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42  the SQLITE_DISAB
1710: 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67  LE_LFS macro mig
1720: 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66  ht still be usef
1730: 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61  ul..**.** Simila
1740: 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61  r is true for Ma
1750: 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20  c OS X.  LFS is 
1760: 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f  only supported o
1770: 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64  n Mac OS X 9 and
1780: 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64   later..*/.#ifnd
1790: 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c  ef SQLITE_DISABL
17a0: 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f  E_LFS.# define _
17b0: 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20  LARGE_FILE      
17c0: 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c   1.# ifndef _FIL
17d0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20  E_OFFSET_BITS.# 
17e0: 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f    define _FILE_O
17f0: 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20  FFSET_BITS 64.# 
1800: 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f  endif.# define _
1810: 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45  LARGEFILE_SOURCE
1820: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 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 31 22 0a 23 64       "3.8.11".#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 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  011.#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 37 2d 32 37 20 31 33    "2015-07-27 13
3160: 3a 34 39 3a 34 31 20 62 38 65 39 32 32 32 37 61  :49:41 b8e92227a
3170: 34 36 39 64 65 36 37 37 61 36 36 64 61 36 32 65  469de677a66da62e
3180: 34 33 36 31 66 30 39 39 63 30 62 37 39 64 30 22  4361f099c0b79d0"
3190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31a0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
31b0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
31c0: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
31d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
31e0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
31f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
3200: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
3210: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
3220: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
3230: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
3240: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
3250: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
3260: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3270: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
3280: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
3290: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
32a0: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
32b0: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
32c0: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
32d0: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
32e0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
32f0: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
3300: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
3310: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
3320: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
3330: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
3340: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
3350: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
3360: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
3370: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69  ader, and thus i
3380: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
3390: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
33a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
33b0: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
33c0: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
33d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
33e0: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
33f0: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
3400: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
3410: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
3420: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
3430: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
3440: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
3450: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3460: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
3470: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
3480: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
3490: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
34a0: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
34b0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
34c0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34d0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
34e0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
34f0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
3500: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
3510: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
3520: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
3530: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
3540: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
3550: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
3560: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
3570: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
3580: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
3590: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
35a0: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
35b0: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
35c0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
35d0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
35e0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
35f0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
3600: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
3610: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
3620: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
3630: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
3640: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
3650: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
3660: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
3670: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
3680: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
3690: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
36a0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
36b0: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
36c0: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
36d0: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
36e0: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
36f0: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
3700: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
3710: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
3720: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
3730: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
3740: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
3750: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
3760: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
3770: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
3780: 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f  sion[] = SQLITE_
3790: 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f  VERSION;.SQLITE_
37a0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
37b0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
37c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
37d0: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
37e0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
37f0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3810: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
3820: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
3830: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62  CALL sqlite3_lib
3840: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
3850: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
3860: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
3870: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
3880: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
3890: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
38a0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
38b0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
38c0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
38d0: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
38e0: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
38f0: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
3900: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
3910: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
3920: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
3930: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
3940: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
3950: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
3960: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
3970: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
3980: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
3990: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
39a0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
39b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
39c0: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
39d0: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
39e0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
39f0: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
3a00: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
3a10: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
3a20: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
3a30: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
3a40: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
3a50: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
3a60: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3a70: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
3a80: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3a90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
3aa0: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
3ab0: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
3ac0: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
3ad0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
3ae0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
3af0: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
3b00: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
3b10: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
3b20: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3b30: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
3b40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3b50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
3b60: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
3b70: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
3b80: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
3b90: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
3ba0: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
3bb0: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
3bc0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
3bd0: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
3be0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
3bf0: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
3c00: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
3c10: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
3c20: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
3c30: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
3c40: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
3c50: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
3c60: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
3c70: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
3c80: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
3c90: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
3ca0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
3cb0: 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f  ptName);.SQLITE_
3cc0: 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
3cd0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3ce0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
3cf0: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
3d00: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
3d10: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
3d20: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
3d30: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
3d40: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
3d50: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
3d60: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3d70: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
3d80: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
3d90: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
3da0: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65  th mutexing code
3db0: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20   omitted due to 
3dc0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
3dd0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69  HREADSAFE] compi
3de0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62  le-time option b
3df0: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a  eing set to 0..*
3e00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
3e10: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
3e20: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
3e30: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
3e40: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
3e50: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
3e60: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20  ssor macro is 1 
3e70: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
3e80: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
3e90: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
3ea0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
3eb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
3ec0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
3ed0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
3ee0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
3ef0: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
3f00: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
3f10: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
3f20: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
3f30: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
3f40: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
3f50: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
3f60: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
3f70: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
3f80: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
3f90: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
3fa0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
3fb0: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
3fc0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
3fd0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
3fe0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
3ff0: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
4000: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
4010: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  led..** ^The def
4020: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
4030: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20   for mutexes to 
4040: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  be enabled..**.*
4050: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
4060: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20   can be used by 
4070: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
4080: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
4090: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
40a0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
40b0: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
40c0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
40d0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
40e0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
40f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
4100: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
4110: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
4120: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
4130: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
4140: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
4150: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
4160: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
4170: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
4180: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
4190: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
41a0: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32  READSAFE=1 or =2
41b0: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72   then mutexes ar
41c0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
41d0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20  ault but.** can 
41e0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74  be fully or part
41f0: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75  ially disabled u
4200: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  sing a call to [
4210: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4220: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65  ].** with the ve
4230: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  rbs [SQLITE_CONF
4240: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
4250: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
4260: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a  _MULTITHREAD],.*
4270: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  * or [SQLITE_CON
4280: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e  FIG_SERIALIZED].
4290: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
42a0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
42b0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
42c0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
42d0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
42e0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
42f0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
4300: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
4310: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
4320: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
4330: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
4340: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
4350: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
4360: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
4370: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
4380: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
4390: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
43a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
43b0: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
43c0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
43d0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
43e0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
43f0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
4400: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
4410: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
4420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
4430: 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  afe(void);../*.*
4440: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
4450: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
4460: 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52  Handle.** KEYWOR
4470: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
4480: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
4490: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
44a0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
44b0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
44c0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
44d0: 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
44e0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
44f0: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
4500: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
4510: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
4520: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
4530: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
4540: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
4550: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
4560: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
4570: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
4580: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
4590: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
45a0: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
45b0: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
45c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
45d0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
45e0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61  e3_close_v2()] a
45f0: 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  re its destructo
4600: 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  rs.  There are m
4610: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74  any other.** int
4620: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
4630: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
4640: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
4650: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
4660: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
4670: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
4680: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
4690: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
46a0: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
46b0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
46c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
46d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
46e0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
46f0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
4700: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a   Integer Types.*
4710: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
4720: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f  te_int64 sqlite_
4730: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63  uint64.**.** Bec
4740: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f  ause there is no
4750: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20   cross-platform 
4760: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36  way to specify 6
4770: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79  4-bit integer ty
4780: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  pes.** SQLite in
4790: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20  cludes typedefs 
47a0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65  for 64-bit signe
47b0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69  d and unsigned i
47c0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  ntegers..**.** T
47d0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
47e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e   and sqlite3_uin
47f0: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66  t64 are the pref
4800: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e  erred type defin
4810: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73  itions..** The s
4820: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20  qlite_int64 and 
4830: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
4840: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65  pes are supporte
4850: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
4860: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
4870: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
4880: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
4890: 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  and sqlite_int64
48a0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
48b0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a   integer values.
48c0: 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33  ** between -9223
48d0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20  372036854775808 
48e0: 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38  and +92233720368
48f0: 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69  54775807 inclusi
4900: 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ve.  ^The.** sql
4910: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20  ite3_uint64 and 
4920: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
4930: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
4940: 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a  teger values .**
4950: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b   between 0 and +
4960: 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35  1844674407370955
4970: 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a  1615 inclusive..
4980: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
4990: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79  _INT64_TYPE.  ty
49a0: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  pedef SQLITE_INT
49b0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69  64_TYPE sqlite_i
49c0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
49d0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
49e0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
49f0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20  e_uint64;.#elif 
4a00: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
4a10: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42  ) || defined(__B
4a20: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70  ORLANDC__).  typ
4a30: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c  edef __int64 sql
4a40: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
4a50: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f  edef unsigned __
4a60: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
4a70: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70  t64;.#else.  typ
4a80: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  edef long long i
4a90: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  nt sqlite_int64;
4aa0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
4ab0: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  ned long long in
4ac0: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  t sqlite_uint64;
4ad0: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20  .#endif.typedef 
4ae0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
4af0: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65  ite3_int64;.type
4b00: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  def sqlite_uint6
4b10: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4 sqlite3_uint64
4b20: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70  ;../*.** If comp
4b30: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63  iling for a proc
4b40: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73  essor that lacks
4b50: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
4b60: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73  support,.** subs
4b70: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66  titute integer f
4b80: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  or floating-poin
4b90: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
4ba0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
4bb0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
4bc0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
4bd0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
4be0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
4bf0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
4c00: 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44   Connection.** D
4c10: 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
4c20: 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
4c30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
4c40: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
4c50: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
4c60: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
4c70: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
4c80: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
4c90: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
4ca0: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
4cb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
4cc0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
4cd0: 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ] if.** the [sql
4ce0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
4cf0: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
4d00: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
4d10: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
4d20: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
4d30: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
4d40: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
4d50: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
4d60: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
4d70: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
4d80: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
4d90: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
4da0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
4db0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
4dc0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
4dd0: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
4de0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4df0: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
4e00: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
4e10: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
4e20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
4e30: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
4e40: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
4e50: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f  tements.** and/o
4e60: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
4e70: 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68  ite3_backups, th
4e80: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4e90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d  connection becom
4ea0: 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c  es.** an unusabl
4eb0: 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68  e "zombie" which
4ec0: 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
4ed0: 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  lly be deallocat
4ee0: 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c  ed when the.** l
4ef0: 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ast prepared sta
4f00: 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69  tement is finali
4f10: 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20  zed or the last 
4f20: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69  sqlite3_backup i
4f30: 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20  s.** finished.  
4f40: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
4f50: 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
4f60: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
4f70: 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73   use with.** hos
4f80: 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74  t languages that
4f90: 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c   are garbage col
4fa0: 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72  lected, and wher
4fb0: 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77  e the order in w
4fc0: 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74  hich.** destruct
4fd0: 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69  ors are called i
4fe0: 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a  s arbitrary..**.
4ff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
5000: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
5010: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
5020: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
5030: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a  ed statements],.
5040: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
5050: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
5060: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  all [BLOB handle
5070: 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  s], and .** [sql
5080: 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69  ite3_backup_fini
5090: 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c  sh | finish] all
50a0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
50b0: 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69  ] objects associ
50c0: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
50d0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
50e0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
50f0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
5100: 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a  he object.  ^If.
5110: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ** sqlite3_close
5120: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
5130: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
5140: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
5150: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
5160: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
5170: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
5180: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
5190: 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  and/or.** [sqlit
51a0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
51b0: 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ts then it retur
51c0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61  ns [SQLITE_OK] a
51d0: 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74  nd the deallocat
51e0: 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72  ion.** of resour
51f0: 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20  ces is deferred 
5200: 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61  until all [prepa
5210: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
5220: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
5230: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
5240: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
5250: 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f   are also destro
5260: 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  yed..**.** ^If a
5270: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
5280: 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ct is destroyed 
5290: 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74  while a transact
52a0: 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20  ion is open,.** 
52b0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
52c0: 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
52d0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
52e0: 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65  .** The C parame
52f0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
5300: 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73  close(C)] and [s
5310: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
5320: 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  C)].** must be e
5330: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
5340: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
5350: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
5360: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
5370: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
5380: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
5390: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
53a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
53b0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74  n_v2()], and not
53c0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73   previously clos
53d0: 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  ed..** ^Calling 
53e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
53f0: 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  or sqlite3_close
5400: 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
5410: 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67  L pointer.** arg
5420: 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c  ument is a harml
5430: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
5440: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
5450: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
5460: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
5470: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
5480: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
5490: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  LL sqlite3_close
54a0: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
54b0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
54c0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
54d0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
54e0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
54f0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
5500: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
5510: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
5520: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
5530: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
5540: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
5550: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
5560: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
5570: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
5580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5590: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
55a0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
55b0: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
55c0: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
55d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
55e0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
55f0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
5600: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
5610: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
5620: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
5630: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
5640: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
5650: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
5660: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
5670: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
5680: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
5690: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
56a0: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
56b0: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
56c0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
56d0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
56e0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
56f0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
5700: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
5710: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
5720: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
5730: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
5740: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
5750: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
5760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
5770: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
5780: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
5790: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
57a0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
57b0: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
57c0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
57d0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
57e0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
57f0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
5800: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
5810: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
5820: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
5830: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
5840: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
5850: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
5860: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
5870: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
5880: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
5890: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
58a0: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
58b0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
58c0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
58d0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
58e0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
58f0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
5900: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
5910: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
5920: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
5930: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
5940: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
5950: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
5960: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
5970: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
5980: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
5990: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
59a0: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
59b0: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
59c0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
59d0: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
59e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
59f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
5a00: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
5a10: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
5a20: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
5a30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
5a40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
5a50: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
5a60: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
5a70: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
5a80: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
5a90: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
5aa0: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
5ab0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
5ac0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
5ad0: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
5ae0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
5af0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
5b00: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
5b10: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
5b20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
5b30: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
5b40: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
5b50: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
5b60: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
5b70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
5b80: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
5b90: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
5ba0: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
5bb0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
5bc0: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
5bd0: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
5be0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
5bf0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
5c00: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
5c10: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
5c20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
5c30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
5c40: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
5c50: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
5c60: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
5c70: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
5c80: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
5c90: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
5ca0: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
5cb0: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
5cc0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
5cd0: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
5ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
5cf0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
5d00: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
5d10: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
5d20: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
5d30: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
5d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
5d50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
5d60: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
5d70: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
5d80: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
5d90: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
5da0: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
5db0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
5dc0: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
5dd0: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
5de0: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
5df0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
5e00: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
5e10: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
5e20: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
5e30: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
5e40: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
5e50: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
5e60: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
5e70: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
5e80: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
5e90: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
5ea0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
5eb0: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
5ec0: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
5ed0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
5ee0: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
5ef0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
5f00: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
5f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
5f20: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
5f30: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
5f40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
5f50: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
5f60: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
5f70: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
5f80: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
5f90: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
5fa0: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
5fb0: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
5fc0: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
5fd0: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
5fe0: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
5ff0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
6000: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
6010: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
6020: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
6030: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
6040: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
6050: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
6060: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
6070: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
6080: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
6090: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
60a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
60b0: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
60c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
60d0: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
60e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
60f0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
6100: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
6110: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
6120: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
6130: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
6140: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
6150: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
6160: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
6170: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
6180: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
6190: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
61a0: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
61b0: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
61c0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
61d0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
61e0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
61f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
6200: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
6210: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
6220: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6240: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
6250: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
6260: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
6270: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6290: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
62a0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
62b0: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
62c0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
62d0: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
62e0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
62f0: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
6320: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
6330: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
6340: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6360: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
6370: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
6380: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
6390: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
63a0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
63b0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
63c0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
63d0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
63e0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
63f0: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
6400: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
6410: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
6420: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
6430: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
6440: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
6450: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
6460: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
6470: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
6480: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
6490: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
64a0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
64b0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
64c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64d0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
64e0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
64f0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
6500: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
6510: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
6520: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
6530: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
6540: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
6550: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
6560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
6570: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
6580: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
6590: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
65a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
65b0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
65c0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
65d0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
65e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65f0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
6600: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
6610: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
6620: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
6630: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
6640: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
6650: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
6660: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
6670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6680: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
6690: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
66a0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
66b0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
66c0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
66d0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
66e0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
66f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
6700: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
6710: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
6720: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
6730: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
6740: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
6750: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
6760: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
6770: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
6780: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
6790: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
67a0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
67b0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
67c0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
67d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67e0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
67f0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
6800: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
6810: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
6820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6830: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
6840: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
6850: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
6860: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
6870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
6880: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
6890: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
68a0: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
68b0: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
68d0: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
68e0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
68f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
6900: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
6910: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
6920: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
6930: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
6940: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
6950: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
6960: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
6970: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
6980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6990: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
69a0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
69b0: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
69c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
69d0: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
69e0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
69f0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
6a00: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
6a10: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6a20: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
6a30: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
6a40: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
6a50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6a60: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
6a70: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
6a80: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
6a90: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
6aa0: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
6ab0: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
6ac0: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
6ad0: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
6ae0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
6af0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
6b00: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
6b10: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
6b20: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
6b30: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
6b40: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
6b50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6b60: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
6b70: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
6b80: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
6b90: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
6ba0: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
6bb0: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
6bc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
6bd0: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
6be0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
6bf0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
6c00: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
6c10: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
6c20: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
6c30: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
6c40: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
6c50: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
6c60: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
6c70: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
6c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6c90: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
6ca0: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
6cb0: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
6cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
6cd0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
6ce0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
6cf0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
6d00: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
6d20: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
6d30: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
6d40: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
6d50: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
6d60: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
6d70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6d80: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
6d90: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
6da0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
6db0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
6dc0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
6dd0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
6de0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
6df0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
6e00: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
6e10: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
6e20: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
6e30: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
6e40: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
6e50: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
6e60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
6e70: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
6e80: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
6e90: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
6ea0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
6eb0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
6ec0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
6ed0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
6ee0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
6ef0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
6f00: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
6f10: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
6f20: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
6f30: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
6f40: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
6f50: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
6f60: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
6f70: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
6f80: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
6f90: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
6fa0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
6fb0: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
6fc0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
6fd0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
6fe0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
6ff0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
7000: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
7010: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
7020: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
7030: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
7040: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
7050: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
7060: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
7070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
7080: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
7090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
70a0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
70c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
70d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
70e0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
70f0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
7100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
7110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7120: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
7130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7140: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
7150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7160: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
7170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7180: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
71b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
71c0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
71e0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
71f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7200: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
7210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7220: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
7230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
7240: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
7250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7260: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
7270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7280: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
7290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
72a0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
72b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
72c0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
72d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
72e0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
72f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7300: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
7310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7320: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
7330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7340: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
7350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7360: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
7370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7380: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
7390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
73a0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
73b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
73c0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
73d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
73e0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
73f0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
7400: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
7410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7420: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
7430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7440: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
7450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7460: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
7470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7480: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
7490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
74a0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
74b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
74c0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
74d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
74e0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
74f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7500: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
7510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7520: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
7530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7540: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
7550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7560: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
7570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7580: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
7590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
75a0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
75b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
75c0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
75d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
75e0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
75f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7600: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
7610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7620: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
7630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7640: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7660: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
7670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7680: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
7690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
76a0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
76b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
76c0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
76d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
76e0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
76f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7700: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
7710: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
7720: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
7730: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
7740: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
7750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
7760: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
7770: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
7780: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
7790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
77a0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
77b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
77c0: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
77d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
77e0: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
77f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
7800: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
7810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7820: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
7830: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7840: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
7850: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7860: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
7870: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
7880: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
7890: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
78a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
78b0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
78c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
78d0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
78e0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
78f0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
7900: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
7910: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
7930: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
7940: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
7950: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
7960: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
7970: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
7980: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
7990: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
79a0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
79b0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
79c0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
79d0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
79e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
79f0: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
7a00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7a10: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
7a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
7a30: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
7a40: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
7a50: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
7a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7a70: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
7a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7a90: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
7aa0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7ab0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
7ac0: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
7ad0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7ae0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7af0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b00: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
7b10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7b20: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
7b30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7b40: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
7b50: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7b60: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
7b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7b80: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
7b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7ba0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
7bb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7bc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
7bd0: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
7be0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7bf0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7c00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c10: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
7c20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7c30: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
7c40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7c50: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
7c60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7c70: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
7c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7c90: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
7ca0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7cb0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
7cc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7cd0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
7ce0: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
7cf0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
7d00: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
7d10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
7d20: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
7d30: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7d40: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<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 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
7d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
7d80: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7d90: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
7da0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
7db0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
7dc0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7dd0: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
7de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
7df0: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
7e00: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
7e10: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
7e20: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
7e30: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
7e40: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
7e50: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
7e60: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
7e70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
7e80: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
7e90: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
7ea0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
7eb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
7ec0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7ed0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
7ee0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7ef0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
7f00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
7f10: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7f20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f40: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
7f50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
7f60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7f70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7f80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7f90: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
7fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
7fb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
7fc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
7fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7fe0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
7ff0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
8000: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
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 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
8030: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
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 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
8070: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
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 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
80b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
80c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
80d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
80e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
80f0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
8100: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
8110: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8120: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8140: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
8150: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
8160: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
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 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
8190: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
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 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
81d0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
8210: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
8220: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8240: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8250: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
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 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
8290: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
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 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
82d0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
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 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
8310: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
8320: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8330: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8350: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
8360: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
8370: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8380: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83a0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
83b0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
83c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
83d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
83e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83f0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
8400: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
8410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
8420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
8430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8440: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
8450: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
8460: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
8470: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
8480: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8490: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
84a0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
84b0: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
84c0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
84d0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
84e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
84f0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
8500: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8510: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
8520: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
8530: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
8540: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
8550: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
8560: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
8570: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
8580: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
8590: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
85a0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
85b0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
85c0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
85d0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
85e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
85f0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8600: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8610: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8620: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8630: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8640: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
8650: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
8660: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8670: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8680: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8690: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
86a0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
86b0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
86c0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
86d0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
86e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
86f0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8700: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8710: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8720: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
8730: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8740: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8750: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8760: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8770: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8780: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8790: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
87a0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
87b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
87c0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
87d0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
87e0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
87f0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8800: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8810: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8820: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8830: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
8840: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
8850: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
8860: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
8870: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
8880: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
8890: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
88a0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
88b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
88c0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
88d0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
88e0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
88f0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
8900: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
8910: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
8920: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
8930: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
8940: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
8950: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
8960: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
8970: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
8980: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
8990: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
89a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
89b0: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
89c0: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
89d0: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
89e0: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
89f0: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
8a00: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
8a10: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
8a20: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
8a30: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
8a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8a50: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
8a60: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
8a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8a80: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
8a90: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8aa0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
8ab0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8ac0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
8ad0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
8ae0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8af0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
8b00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
8b10: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
8b20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
8b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8b40: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
8b50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
8b60: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
8b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
8b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
8ba0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8bb0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
8bc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8bd0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
8be0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
8bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8c00: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
8c10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8c20: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
8c30: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8c40: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
8c50: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
8c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8c70: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
8c80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
8c90: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
8ca0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
8cb0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
8cc0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
8cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
8ce0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
8cf0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
8d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d10: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
8d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8d30: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
8d40: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
8d50: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
8d60: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
8d70: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
8d80: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
8d90: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
8da0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
8db0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
8dc0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
8dd0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
8de0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
8df0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8e00: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8e10: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
8e20: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
8e30: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
8e40: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
8e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8e60: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
8e70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8e80: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
8e90: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
8ea0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8eb0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
8ec0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
8ed0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
8ee0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
8ef0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
8f00: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
8f10: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
8f20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8f30: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
8f40: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
8f50: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
8f60: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
8f70: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
8f80: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
8f90: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
8fa0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
8fb0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
8fc0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
8fd0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
8fe0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
8ff0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
9000: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
9010: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
9020: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
9030: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
9040: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
9050: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
9060: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
9070: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
9080: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
9090: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
90a0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
90b0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
90c0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
90d0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
90e0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
90f0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
9100: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
9110: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
9120: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
9130: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
9140: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
9150: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
9160: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9170: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
9180: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9190: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
91a0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
91b0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
91c0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
91d0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
91e0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
91f0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
9200: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
9210: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
9220: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
9230: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
9240: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
9250: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
9260: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
9270: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
9280: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
9290: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
92a0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
92b0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
92c0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
92d0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
92e0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
92f0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
9300: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
9310: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
9320: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
9330: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
9340: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
9350: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
9360: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
9370: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
9380: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
9390: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
93a0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
93b0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
93c0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
93d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
93e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
93f0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
9400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
9410: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
9420: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
9430: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
9440: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
9450: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
9460: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
9470: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
9480: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
9490: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
94a0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
94b0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
94c0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
94d0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
94e0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
94f0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
9500: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
9510: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
9520: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
9530: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
9540: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
9550: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
9560: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
9570: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
9580: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
9590: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
95a0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
95b0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
95c0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
95d0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
95e0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
95f0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
9600: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
9610: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
9620: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
9630: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
9640: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
9650: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
9660: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
9670: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
9680: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
9690: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
96a0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
96b0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
96c0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
96d0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
96e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
96f0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
9700: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
9710: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9720: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
9730: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
9740: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
9750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9760: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
9770: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
9780: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
9790: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
97a0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
97b0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
97c0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
97d0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
97e0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
97f0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
9800: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9810: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
9820: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
9830: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
9840: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
9850: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9860: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
9870: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
9880: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
9890: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
98a0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
98b0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
98c0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
98d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
98e0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
98f0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
9900: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
9910: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
9920: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
9930: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
9940: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
9950: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
9960: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
9970: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
9980: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9990: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
99a0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
99b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
99c0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
99d0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
99e0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
99f0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
9a00: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
9a10: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
9a20: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
9a30: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
9a40: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
9a50: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
9a60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
9a70: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
9a80: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
9a90: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
9aa0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
9ab0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
9ac0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
9ad0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
9ae0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
9af0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
9b00: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
9b10: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
9b20: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
9b30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9b40: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
9b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
9b60: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
9b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
9b80: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
9b90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9ba0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
9bb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
9bc0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
9bd0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
9be0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
9bf0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
9c00: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
9c10: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
9c20: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
9c30: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
9c40: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
9c50: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
9c60: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
9c70: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
9c80: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
9c90: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
9ca0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
9cb0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
9cc0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
9cd0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
9ce0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
9cf0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
9d00: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
9d10: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
9d20: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
9d30: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
9d40: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
9d50: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
9d60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
9d70: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
9d80: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
9d90: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
9da0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9db0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
9dc0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
9dd0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
9de0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
9df0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
9e00: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
9e10: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
9e20: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
9e30: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
9e40: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
9e50: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
9e60: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
9e70: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
9e80: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
9e90: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
9ea0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
9eb0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
9ec0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
9ed0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
9ee0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
9ef0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
9f00: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
9f10: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
9f20: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
9f30: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
9f40: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
9f50: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
9f60: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
9f70: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
9f80: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
9f90: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
9fa0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
9fb0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
9fc0: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
9fd0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
9fe0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
9ff0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
a000: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
a010: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
a020: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
a030: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
a040: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
a050: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
a060: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
a070: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
a080: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
a090: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
a0a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a0b0: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
a0c0: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
a0d0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
a0e0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
a0f0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
a100: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
a110: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
a120: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
a130: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
a140: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
a150: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
a160: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
a170: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
a180: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
a190: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
a1a0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
a1b0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
a1c0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a1d0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
a1e0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
a1f0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
a200: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
a210: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
a220: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
a230: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
a240: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a250: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
a260: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
a270: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
a280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
a290: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a2a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
a2b0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
a2c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
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 38  TE_IOCAP_ATOMIC8
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 31  TE_IOCAP_ATOMIC1
a310: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
a320: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a330: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
a340: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a350: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
a360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
a370: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
a380: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
a390: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
a3a0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
a3b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
a3c0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
a3d0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
a3e0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
a3f0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a400: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
a410: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
a420: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
a430: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
a440: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
a450: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
a460: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
a470: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
a480: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
a490: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
a4a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
a4b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
a4c0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
a4d0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
a4e0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
a4f0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
a500: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
a510: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
a520: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
a530: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
a540: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
a550: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
a560: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
a570: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
a580: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a590: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
a5a0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
a5b0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
a5c0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
a5d0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
a5e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
a5f0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
a600: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
a610: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
a620: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
a630: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
a640: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
a650: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
a660: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
a670: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
a680: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
a690: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
a6a0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
a6b0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
a6c0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
a6d0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
a6e0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
a6f0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
a700: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a710: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
a720: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
a730: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
a740: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
a750: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
a760: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
a770: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
a780: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
a790: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
a7a0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a7b0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a7c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
a7d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a7e0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
a7f0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
a800: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
a810: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
a820: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
a830: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
a840: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
a850: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
a860: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
a870: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
a880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a890: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
a8a0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
a8b0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
a8c0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
a8d0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
a8e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a8f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
a900: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
a910: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
a920: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
a930: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
a940: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a950: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
a960: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
a970: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
a980: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
a990: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
a9a0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
a9b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
a9c0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
a9d0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
a9e0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
a9f0: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
aa00: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
aa10: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
aa20: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
aa30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
aa40: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
aa50: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
aa60: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
aa70: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
aa80: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
aa90: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
aaa0: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
aab0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
aac0: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
aad0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
aae0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
aaf0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
ab00: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
ab10: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
ab20: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
ab30: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
ab40: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
ab50: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
ab60: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
ab70: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
ab80: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
ab90: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
aba0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
abb0: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
abc0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
abd0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
abe0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
abf0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ac00: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
ac10: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
ac20: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
ac30: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
ac40: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
ac50: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
ac60: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
ac70: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
ac80: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
ac90: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
aca0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
acb0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
acc0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
acd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
ace0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
acf0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
ad00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
ad10: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
ad20: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
ad30: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ad40: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
ad50: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
ad60: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
ad70: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
ad80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
ad90: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
ada0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
adb0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
adc0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
add0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
ade0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
adf0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
ae00: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
ae10: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
ae20: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
ae30: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
ae40: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
ae50: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
ae60: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
ae70: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
ae80: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
ae90: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
aea0: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
aeb0: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
aec0: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
aed0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
aee0: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
aef0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
af00: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
af10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
af20: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
af30: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
af40: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
af50: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
af60: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
af70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
af80: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
af90: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
afa0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
afb0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
afc0: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
afd0: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
afe0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
aff0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
b000: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
b010: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
b020: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
b030: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
b040: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
b050: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
b060: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
b070: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
b080: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
b090: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b0a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b0b0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b0c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
b0d0: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
b0e0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
b0f0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
b100: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
b110: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
b120: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
b130: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
b140: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
b150: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
b160: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
b170: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b180: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
b190: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
b1a0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
b1b0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
b1c0: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
b1d0: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
b1e0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
b1f0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
b200: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
b210: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
b220: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
b230: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
b240: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
b250: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
b260: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
b270: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
b280: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
b290: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b2a0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b2b0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b2d0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
b2e0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
b2f0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
b300: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b310: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
b320: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
b330: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
b340: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
b350: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
b360: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b370: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
b380: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
b390: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
b3a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b3b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b3c0: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c  MITTED]].** No l
b3d0: 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a  onger in use..**
b3e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3f0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a  _FCNTL_SYNC]].**
b400: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b410: 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20  TL_SYNC] opcode 
b420: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
b430: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
b440: 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f  e and.** sent to
b450: 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61   the VFS immedia
b460: 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20  tely before the 
b470: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
b480: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20  invoked on a.** 
b490: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65  database file de
b4a0: 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66  scriptor. Or, if
b4b0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b4c0: 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  d is not invoked
b4d0: 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65   .** because the
b4e0: 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67   user has config
b4f0: 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68  ured SQLite with
b500: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e   .** [PRAGMA syn
b510: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
b520: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
b530: 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  F] it is invoked
b540: 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66   in place .** of
b550: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
b560: 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73  d. In most cases
b570: 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72  , the pointer ar
b580: 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69  gument passed wi
b590: 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d  th.** this file-
b5a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e  control is NULL.
b5b0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65   However, if the
b5c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b5d0: 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a  s being synced.*
b5e0: 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d  * as part of a m
b5f0: 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f  ulti-database co
b600: 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65  mmit, the argume
b610: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e  nt points to a n
b620: 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
b630: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
b640: 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ng the transacti
b650: 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e  ons master-journ
b660: 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46  al file name. VF
b670: 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20  Ses that .** do 
b680: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
b690: 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65  gnal should sile
b6a0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b6b0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b6c0: 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64  tions .** should
b6d0: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
b6e0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b6f0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
b700: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
b710: 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20  may .** disrupt 
b720: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
b730: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
b740: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
b750: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
b760: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b770: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
b780: 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b  SETWO]].** The [
b790: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b7a0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70  MIT_PHASETWO] op
b7b0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
b7c0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
b7d0: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65  SQLite.** and se
b7e0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66  nt to the VFS af
b7f0: 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ter a transactio
b800: 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69  n has been commi
b810: 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  tted immediately
b820: 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74  .** but before t
b830: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75  he database is u
b840: 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74  nlocked. VFSes t
b850: 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  hat do not need 
b860: 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73  this signal.** s
b870: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
b880: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
b890: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  e. Applications 
b8a0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a  should not call.
b8b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
b8c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
b8d0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
b8e0: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
b8f0: 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65  rupt the .** ope
b900: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
b910: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
b920: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
b930: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
b940: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b950: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a  IN32_AV_RETRY]].
b960: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b970: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b980: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20  ETRY] opcode is 
b990: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
b9a0: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72  e automatic.** r
b9b0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20  etry counts and 
b9c0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65  intervals for ce
b9d0: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f  rtain disk I/O o
b9e0: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  perations for th
b9f0: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46  e.** windows [VF
ba00: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  S] in order to p
ba10: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73  rovide robustnes
ba20: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63  s in the presenc
ba30: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72  e of.** anti-vir
ba40: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79  us programs.  By
ba50: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69   default, the wi
ba60: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72  ndows VFS will r
ba70: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a  etry file read,.
ba80: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61  ** file write, a
ba90: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f  nd file delete o
baa0: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20  perations up to 
bab0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61  10 times, with a
bac0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20   delay.** of 25 
bad0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66  milliseconds bef
bae0: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65  ore the first re
baf0: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65  try and with the
bb00: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e   delay increasin
bb10: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74  g.** by an addit
bb20: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65  ional 25 millise
bb30: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20  conds with each 
bb40: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79  subsequent retry
bb50: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bb60: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74  e allows these t
bb70: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65  wo values (10 re
bb80: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c  tries and 25 mil
bb90: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c  liseconds of del
bba0: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a  ay).** to be adj
bbb0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75  usted.  The valu
bbc0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66  es are changed f
bbd0: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  or all database 
bbe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77  connections.** w
bbf0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
bc00: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67  rocess.  The arg
bc10: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
bc20: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  er to an array o
bc30: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72  f two.** integer
bc40: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
bc50: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20  t integer i the 
bc60: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20  new retry count 
bc70: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  and the second.*
bc80: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65  * integer is the
bc90: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68   delay.  If eith
bca0: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65  er integer is ne
bcb0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
bcc0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e   setting.** is n
bcd0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69  ot changed but i
bce0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72  nstead the prior
bcf0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73   value of that s
bd00: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65  etting is writte
bd10: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72  n.** into the ar
bd20: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77  ray entry, allow
bd30: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20  ing the current 
bd40: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74  retry settings t
bd50: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67  o be.** interrog
bd60: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61  ated.  The zDbNa
bd70: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
bd80: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  ignored..**.** <
bd90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bda0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a  L_PERSIST_WAL]].
bdb0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
bdc0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
bdd0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  L] opcode is use
bde0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
bdf0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
be00: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65  ent [WAL | Write
be10: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74   Ahead Log] sett
be20: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ing.  By default
be30: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a  , the auxiliary.
be40: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c  ** write ahead l
be50: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  og and shared me
be60: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20  mory files used 
be70: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  for transaction 
be80: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61  control.** are a
be90: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
bea0: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61  eted when the la
beb0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  test connection 
bec0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
bed0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74  ** closes.  Sett
bee0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57  ing persistent W
bef0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74  AL mode causes t
bf00: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65  hose files to pe
bf10: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63  rsist after.** c
bf20: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e  lose.  Persistin
bf30: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75  g the files is u
bf40: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72  seful when other
bf50: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20   processes that 
bf60: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77  do not.** have w
bf70: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20  rite permission 
bf80: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  on the directory
bf90: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
bfa0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
bfb0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68  nt.** to read th
bfc0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
bfd0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20   as the WAL and 
bfe0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
bff0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a  les must exist.*
c000: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74  * in order for t
c010: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62  he database to b
c020: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  e readable.  The
c030: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
c040: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
c050: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
c060: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
c070: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
c080: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
c090: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
c0a0: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
c0b0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57  ble persistent W
c0c0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  AL mode or 1 to 
c0d0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  enable persisten
c0e0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20  t.** WAL mode.  
c0f0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c100: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c110: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c120: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c130: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65   WAL persistence
c140: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
c150: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c160: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
c170: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
c180: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c190: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
c1a0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
c1b0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
c1c0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
c1d0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d  tent "powersafe-
c1e0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50  overwrite" or "P
c1f0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54  SOW" setting.  T
c200: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a  he PSOW setting.
c210: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  ** determines th
c220: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  e [SQLITE_IOCAP_
c230: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c240: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a  ITE] bit of the.
c250: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63  ** xDeviceCharac
c260: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
c270: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  s. The fourth pa
c280: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
c290: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
c2a0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
c2b0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
c2c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c2d0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
c2e0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
c2f0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64  o disable zero-d
c300: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20  amage mode or 1 
c310: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64  to enable zero-d
c320: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20  amage.** mode.  
c330: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69  If the integer i
c340: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73  s -1, then it is
c350: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
c360: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  h the current.**
c370: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
c380: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
c390: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c3a0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  NTL_OVERWRITE]].
c3b0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
c3c0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
c3d0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
c3e0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
c3f0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
c400: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
c410: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
c420: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
c430: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
c440: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
c450: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
c460: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
c470: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
c480: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
c490: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
c4a0: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
c4b0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
c4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c4d0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c4e0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
c4f0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c500: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
c510: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
c520: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20  the names of.** 
c530: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74  all [VFSes] in t
c540: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54  he VFS stack.  T
c550: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20  he names are of 
c560: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e  all VFS shims an
c570: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62  d the.** final b
c580: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20  ottom-level VFS 
c590: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  are written into
c5a0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
c5b0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
c5c0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
c5d0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73   the result is s
c5e0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61  tored in the cha
c5f0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74  r* variable.** t
c600: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70  hat the fourth p
c610: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
c620: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c630: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a  l()] points to..
c640: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73  ** The caller is
c650: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
c660: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
c670: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20  ory when done.  
c680: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66  As with.** all f
c690: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69  ile-control acti
c6a0: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ons, there is no
c6b0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
c6c0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c  this will actual
c6d0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e  ly.** do anythin
c6e0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75  g.  Callers shou
c6f0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ld initialize th
c700: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
c710: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   to a NULL.** po
c720: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68  inter in case th
c730: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  is file-control 
c740: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
c750: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63  ed.  This file-c
c760: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74  ontrol.** is int
c770: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f  ended for diagno
c780: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a  stic use only..*
c790: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c7a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
c7b0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
c7c0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
c7d0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
c7e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c7f0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
c800: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
c810: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
c820: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
c830: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
c840: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
c850: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
c860: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
c870: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
c880: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
c890: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
c8a0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
c8b0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
c8c0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
c8d0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
c8e0: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
c8f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
c900: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
c910: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
c920: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
c930: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
c940: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
c950: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
c960: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
c970: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
c980: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
c990: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
c9a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c9b0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
c9c0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
c9d0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
c9e0: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
c9f0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
ca00: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
ca10: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
ca20: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ca30: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
ca40: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
ca50: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
ca60: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
ca70: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
ca80: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
ca90: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
caa0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
cab0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
cac0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
cad0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
cae0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
caf0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
cb00: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
cb10: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
cb20: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
cb30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb40: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
cb50: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
cb60: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
cb70: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
cb80: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
cb90: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
cba0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
cbb0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
cbc0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
cbd0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
cbe0: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
cbf0: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
cc00: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
cc10: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
cc20: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
cc30: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
cc40: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
cc50: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
cc60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
cc70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
cc80: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
cc90: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
cca0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
ccb0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
ccc0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
ccd0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
cce0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
ccf0: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
cd00: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
cd10: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
cd20: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
cd30: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
cd40: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
cd50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
cd60: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
cd70: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
cd80: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
cd90: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
cda0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
cdb0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
cdc0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
cdd0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
cde0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
cdf0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ce00: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ce10: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ce20: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
ce30: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
ce40: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
ce50: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
ce60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
ce70: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
ce80: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
ce90: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
cea0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
ceb0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
cec0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
ced0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
cee0: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
cef0: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
cf00: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
cf10: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
cf20: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
cf30: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
cf40: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
cf50: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
cf60: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
cf70: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
cf80: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
cf90: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
cfa0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
cfb0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
cfc0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
cfd0: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
cfe0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
cff0: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
d000: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
d010: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
d020: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
d030: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
d040: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
d050: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
d060: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
d070: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
d080: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
d090: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
d0a0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
d0b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d0c0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
d0d0: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
d0e0: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
d0f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
d100: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
d110: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
d120: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
d130: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
d140: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
d150: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
d160: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
d170: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
d180: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
d190: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
d1a0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
d1b0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
d1c0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
d1d0: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
d1e0: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
d1f0: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
d200: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
d210: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
d220: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
d230: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
d240: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
d250: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
d260: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
d270: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
d280: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
d290: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
d2a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d2b0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
d2c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d2d0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
d2e0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
d2f0: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
d300: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
d310: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
d320: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
d330: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
d340: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
d350: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
d360: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
d370: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
d380: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
d390: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
d3a0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
d3b0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
d3c0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
d3d0: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
d3e0: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
d3f0: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
d400: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
d410: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
d420: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
d430: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
d440: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
d450: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
d460: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
d470: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
d480: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
d490: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
d4a0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
d4b0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
d4c0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
d4d0: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
d4e0: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
d4f0: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
d500: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d510: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
d520: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
d530: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
d540: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
d550: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
d560: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
d570: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
d580: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
d590: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
d5a0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
d5b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
d5c0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
d5d0: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
d5e0: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
d5f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
d600: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
d610: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
d620: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
d630: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
d640: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
d650: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
d660: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
d670: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
d680: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
d690: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d6a0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
d6b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d6c0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
d6d0: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
d6e0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
d6f0: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
d700: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
d710: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
d720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
d730: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
d740: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
d750: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
d760: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
d770: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
d780: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
d790: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
d7a0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
d7b0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
d7c0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
d7d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d7e0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
d7f0: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d810: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
d820: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
d830: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
d840: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
d850: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
d860: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
d870: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
d880: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
d890: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
d8a0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
d8b0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
d8c0: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
d8d0: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
d8e0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
d8f0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
d900: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
d910: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
d920: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d930: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
d940: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d950: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
d960: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
d970: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
d980: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
d990: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
d9a0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
d9b0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
d9c0: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
d9d0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
d9e0: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
d9f0: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
da00: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
da10: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
da20: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
da30: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
da40: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
da50: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
da60: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
da70: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
da80: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
da90: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
daa0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
dab0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
dad0: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
dae0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
daf0: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
db00: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
db10: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
db20: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
db30: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
db40: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
db50: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
db60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
db70: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
db80: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
db90: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
dba0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
dbb0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
dbc0: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
dbd0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
dbe0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
dbf0: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
dc00: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ode.  .** </ul>.
dc10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
dc20: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
dc30: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
dc40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
dc50: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dc60: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
dc70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc80: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
dc90: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
dca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dcb0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
dcc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
dcd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dce0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
dcf0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
dd00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dd10: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
dd20: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
dd30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dd40: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
dd50: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
dd60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dd70: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
dd80: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
dd90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dda0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
ddb0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
ddc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
ddd0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
dde0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
ddf0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
de00: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
de10: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
de20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
de30: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
de40: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
de50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
de60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
de70: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
de80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
de90: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
dea0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
deb0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
dec0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
ded0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
dee0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
def0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
df00: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
df10: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
df20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
df30: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
df40: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
df50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
df60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
df70: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
df80: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
df90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dfa0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
dfb0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
dfc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dfd0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
dfe0: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
dff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e000: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
e010: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
e020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e030: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
e040: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
e050: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e060: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
e070: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
e080: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e090: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
e0a0: 20 20 20 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65         26../* de
e0b0: 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a  precated names *
e0c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e0d0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
e0e0: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
e0f0: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
e100: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
e110: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52  QLITE_SET_LOCKPR
e120: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
e130: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
e140: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
e150: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
e160: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
e170: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c    SQLITE_FCNTL_L
e180: 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a  AST_ERRNO.../*.*
e190: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
e1a0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
e1b0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
e1c0: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
e1d0: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
e1e0: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
e1f0: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
e200: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
e210: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
e220: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
e230: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
e240: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
e250: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
e260: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
e270: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
e280: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
e290: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
e2a0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
e2b0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
e2c0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
e2d0: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
e2e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e2f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
e300: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
e310: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e320: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
e330: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
e340: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
e350: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e360: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
e370: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
e380: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
e390: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
e3a0: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
e3b0: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
e3c0: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
e3d0: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
e3e0: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
e3f0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
e400: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
e410: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
e420: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
e430: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
e440: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
e450: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
e460: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
e470: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
e480: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
e490: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
e4a0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
e4b0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
e4c0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
e4d0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
e4e0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
e4f0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
e500: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
e510: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
e520: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
e530: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
e540: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
e550: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
e560: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
e570: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
e580: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
e590: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
e5a0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
e5b0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
e5c0: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
e5d0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
e5e0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
e5f0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
e600: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
e610: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
e620: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
e630: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
e640: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
e650: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
e660: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
e670: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
e680: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
e690: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
e6a0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
e6b0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
e6c0: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
e6d0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
e6e0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
e6f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
e700: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
e710: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
e720: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
e730: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
e740: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
e750: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
e760: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
e770: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
e780: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
e790: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
e7a0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
e7b0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
e7c0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
e7d0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
e7e0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
e7f0: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
e800: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
e810: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
e820: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
e830: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
e840: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
e850: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
e860: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
e870: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
e880: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
e890: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
e8a0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
e8b0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
e8c0: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
e8d0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
e8e0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
e8f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
e900: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
e910: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
e920: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
e930: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
e940: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
e950: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
e960: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
e970: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
e980: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
e990: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
e9a0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
e9b0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
e9c0: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
e9d0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
e9e0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
e9f0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
ea00: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
ea10: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
ea20: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
ea30: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
ea40: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
ea50: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
ea60: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
ea70: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
ea80: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
ea90: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
eaa0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
eab0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
eac0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
ead0: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
eae0: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
eaf0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
eb00: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
eb10: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
eb20: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
eb30: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
eb40: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
eb50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
eb60: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
eb70: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
eb80: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
eb90: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
eba0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
ebb0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
ebc0: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
ebd0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ebe0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
ebf0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
ec00: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
ec10: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
ec20: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
ec30: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
ec40: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
ec50: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
ec60: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
ec70: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
ec80: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
ec90: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
eca0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
ecb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ecc0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
ecd0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
ece0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
ecf0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
ed00: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
ed10: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ed20: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
ed30: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
ed40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
ed50: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
ed60: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
ed70: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
ed80: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
ed90: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
eda0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
edb0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
edc0: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
edd0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
ede0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
edf0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
ee00: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
ee10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
ee20: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
ee30: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
ee40: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
ee50: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
ee60: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
ee70: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
ee80: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
ee90: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
eea0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
eeb0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
eec0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
eed0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
eee0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
eef0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ef00: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
ef10: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ef20: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
ef30: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ef40: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
ef50: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ef60: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
ef70: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
ef80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
ef90: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
efa0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
efb0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
efc0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
efd0: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
efe0: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
eff0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
f000: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
f010: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
f020: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
f030: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
f040: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
f050: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
f060: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
f070: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
f080: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
f090: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
f0a0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
f0b0: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
f0c0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
f0d0: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
f0e0: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
f0f0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
f100: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
f110: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
f120: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
f130: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
f140: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
f150: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
f160: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
f170: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
f180: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
f190: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
f1a0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
f1b0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
f1c0: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
f1d0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
f1e0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
f1f0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
f200: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
f210: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
f220: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
f230: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
f240: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
f250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
f260: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f270: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
f280: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f290: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
f2a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
f2b0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
f2c0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
f2d0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f2e0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
f2f0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
f300: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
f310: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f320: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
f330: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
f340: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
f350: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
f360: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
f370: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
f380: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
f390: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
f3a0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
f3b0: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
f3c0: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
f3d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
f3e0: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
f3f0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
f400: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
f410: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
f420: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
f430: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
f440: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
f450: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
f460: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
f470: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
f480: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
f490: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
f4a0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
f4b0: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
f4c0: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
f4d0: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
f4e0: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
f4f0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
f500: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
f510: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
f520: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
f530: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
f540: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
f550: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
f560: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
f570: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
f580: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
f590: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
f5a0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
f5b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
f5c0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
f5d0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
f5e0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f5f0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
f600: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
f610: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
f620: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
f630: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
f640: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
f650: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
f660: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
f670: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
f680: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
f690: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
f6a0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
f6b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
f6c0: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
f6d0: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
f6e0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
f6f0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
f700: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
f710: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
f720: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
f730: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
f740: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
f750: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
f760: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
f770: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
f780: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
f790: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f7a0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
f7b0: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
f7c0: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
f7d0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
f7e0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
f7f0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
f800: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
f810: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
f820: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
f830: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
f840: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f850: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
f860: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
f870: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
f880: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
f890: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
f8a0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
f8b0: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
f8c0: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
f8d0: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
f8e0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
f8f0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
f900: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
f910: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
f920: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
f930: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
f940: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
f950: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
f960: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
f970: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
f980: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
f990: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
f9a0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
f9b0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
f9c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
f9d0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
f9e0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
f9f0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
fa00: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
fa10: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
fa20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
fa30: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
fa40: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
fa50: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
fa60: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
fa70: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
fa80: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
fa90: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
faa0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
fab0: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
fac0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
fad0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
fae0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
faf0: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
fb00: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
fb10: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
fb20: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
fb30: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
fb40: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
fb50: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
fb60: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
fb70: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
fb80: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
fb90: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
fba0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
fbb0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
fbc0: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
fbd0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
fbe0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
fbf0: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
fc00: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
fc10: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
fc20: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
fc30: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
fc40: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
fc50: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
fc60: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
fc70: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
fc80: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
fc90: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
fca0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
fcb0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
fcc0: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
fcd0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
fce0: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
fcf0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fd00: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
fd10: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
fd20: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
fd30: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
fd40: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
fd50: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
fd60: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
fd70: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
fd80: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
fd90: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
fda0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
fdb0: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
fdc0: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
fdd0: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
fde0: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
fdf0: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
fe00: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
fe10: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
fe20: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fe30: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
fe40: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
fe50: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
fe60: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
fe70: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
fe80: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
fe90: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
fea0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
feb0: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
fec0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
fed0: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
fee0: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
fef0: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
ff00: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
ff10: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
ff20: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
ff30: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
ff40: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
ff50: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
ff60: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
ff70: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
ff80: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
ff90: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
ffa0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
ffb0: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
ffc0: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
ffd0: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
ffe0: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
fff0: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
10000 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
10010 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
10020 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
10030 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
10040 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
10050 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
10060 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
10070 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
10080 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
10090 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
100a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
100b0 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
100c0 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
100d0 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
100e0 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
100f0 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
10100 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
10110 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
10120 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
10130 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
10140 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
10150 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
10160 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
10170 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
10180 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
10190 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
101a0 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
101b0 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
101c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
101d0 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
101e0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
101f0 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
10200 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
10210 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
10220 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
10230 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
10240 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
10250 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
10260 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
10270 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
10280 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
10290 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
102a0 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
102b0 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
102c0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
102d0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
102e0 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
102f0 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
10300 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
10310 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
10320 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
10330 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
10340 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
10350 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
10360 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10370 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
10380 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
10390 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
103a0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
103b0 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
103c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
103d0 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
103e0 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
103f0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
10400 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
10410 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
10420 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10430 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10440 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
10450 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(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 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10490 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
104a0 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
104b0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
104c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
104d0 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
104e0 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
104f0 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
10500 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10510 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
10520 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
10530 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
10540 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10550 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
10560 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
10570 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
10580 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
10590 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
105a0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
105b0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
105c0 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
105d0 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
105e0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
105f0 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
10600 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
10610 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
10620 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
10630 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
10640 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
10650 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
10660 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
10670 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
10680 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
10690 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
106a0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
106b0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
106c0 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
106d0 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
106e0 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
106f0 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
10700 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
10710 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
10720 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
10730 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
10740 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10750 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
10760 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
10770 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
10780 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
10790 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
107a0 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
107b0 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
107c0 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
107d0 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
107e0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
107f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10800 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10810 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
10820 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10830 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
10840 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
10850 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
10860 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10870 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
10880 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
10890 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
108a0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
108b0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
108c0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
108d0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
108e0 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
108f0 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
10900 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
10910 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
10920 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
10930 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
10940 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
10950 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
10960 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
10970 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
10980 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
10990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
109a0 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
109b0 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
109c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
109d0 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
109e0 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
109f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
10a00 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
10a10 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
10a20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
10a30 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
10a40 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
10a50 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
10a60 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
10a70 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
10a80 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
10a90 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
10aa0 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10ab0 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10ac0 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10ad0 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10ae0 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10af0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
10b00 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10b10 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10b20 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
10b30 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
10b40 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
10b50 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
10b60 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
10b70 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
10b80 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
10b90 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
10ba0 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10bb0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10bc0 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10bd0 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10be0 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10bf0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10c00 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10c10 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
10c20 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
10c30 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10c40 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
10c50 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
10c60 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
10c70 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10c80 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10c90 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
10ca0 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10cb0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10cc0 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10cd0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10ce0 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10cf0 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10d00 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10d10 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
10d20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10d30 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10d40 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
10d50 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10d60 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
10d70 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
10d80 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
10d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10da0 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10db0 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10dc0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10dd0 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10de0 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10df0 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10e00 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10e10 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10e20 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10e30 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10e40 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
10e50 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
10e60 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
10e70 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
10e80 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
10e90 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
10ea0 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10eb0 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10ec0 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10ed0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10ee0 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10ef0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10f00 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10f10 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10f20 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10f30 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10f40 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
10f50 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10f60 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10f70 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10f80 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10f90 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
10fa0 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10fb0 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
10fc0 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
10fd0 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
10fe0 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
10ff0 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
11000 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
11010 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
11020 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
11030 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
11040 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
11050 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
11060 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
11070 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
11080 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
11090 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
110a0 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
110b0 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
110c0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
110d0 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
110e0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
110f0 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
11100 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
11110 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
11120 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11130 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
11140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11150 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
11160 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
11170 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
11180 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
11190 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
111a0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
111b0 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
111c0 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
111d0 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
111e0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
111f0 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
11200 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
11210 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
11220 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
11230 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
11240 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11250 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
11260 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
11270 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
11280 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
11290 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
112a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
112b0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
112c0 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
112d0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
112e0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
112f0 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
11300 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
11310 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
11320 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
11330 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
11340 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
11350 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11360 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
11370 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
11380 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
11390 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
113a0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
113b0 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
113c0 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
113d0 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
113e0 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
113f0 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
11400 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
11410 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
11420 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11430 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
11440 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
11450 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
11460 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
11470 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11480 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
11490 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
114a0 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
114b0 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
114c0 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
114d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
114e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
114f0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
11500 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
11510 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
11520 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
11530 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
11540 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
11550 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
11560 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
11570 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
11580 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11590 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
115a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
115b0 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
115c0 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
115d0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
115e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
115f0 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
11600 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
11610 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
11620 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
11630 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
11640 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11650 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
11660 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
11670 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
11680 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
11690 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
116a0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
116b0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
116c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
116d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
116e0 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
116f0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
11700 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
11710 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
11720 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
11730 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
11740 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
11750 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
11760 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
11770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
11780 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
11790 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
117a0 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
117b0 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
117c0 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
117d0 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
117e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
117f0 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
11800 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
11810 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
11820 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
11830 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
11840 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
11850 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
11860 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
11870 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
11880 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11890 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
118a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
118b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
118c0 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
118d0 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
118e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118f0 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
11900 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
11910 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
11920 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
11930 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
11940 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
11950 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
11960 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
11970 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
11980 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
11990 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
119a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
119b0 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
119c0 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
119d0 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
119e0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
119f0 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
11a00 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
11a10 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
11a20 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
11a30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11a40 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
11a50 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
11a60 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
11a70 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
11a80 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
11a90 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
11aa0 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11ab0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11ac0 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11ad0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11ae0 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11af0 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
11b00 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
11b10 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
11b20 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11b30 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
11b40 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11b50 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
11b60 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
11b70 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
11b80 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
11b90 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
11ba0 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11bb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11bc0 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11bd0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11be0 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11bf0 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11c00 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11c10 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
11c20 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
11c30 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11c40 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
11c50 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
11c60 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
11c70 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
11c80 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
11c90 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
11ca0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11cb0 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11cc0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11cd0 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11ce0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11cf0 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11d00 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11d10 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11d20 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
11d30 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11d40 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
11d50 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
11d60 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
11d70 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
11d80 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
11d90 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11da0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11db0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11dc0 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11dd0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11de0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11df0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11e00 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11e10 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11e20 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11e30 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11e40 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
11e50 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
11e60 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
11e70 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
11e80 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
11e90 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
11ea0 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11eb0 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11ec0 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11ed0 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11ee0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11ef0 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11f00 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11f10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11f20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11f30 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11f40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
11f50 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
11f60 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
11f70 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
11f80 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
11f90 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
11fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11fb0 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
11fc0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
11fd0 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
11fe0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11ff0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
12000 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
12010 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
12020 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
12030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12040 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
12050 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
12060 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
12070 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
12080 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
12090 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
120a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
120b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
120c0 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
120d0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
120e0 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
120f0 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
12100 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
12110 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
12120 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
12130 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
12140 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
12150 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
12160 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
12170 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
12180 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
12190 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
121a0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
121b0 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
121c0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
121d0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
121e0 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
121f0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
12200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12210 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
12220 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
12230 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
12240 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
12250 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
12260 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
12270 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
12280 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51  * failure..*/.SQ
12290 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
122a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
122b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
122c0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
122d0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
122e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ALL sqlite3_shut
122f0 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
12300 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12310 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
12320 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
12330 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12340 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
12350 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
12360 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
12370 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
12380 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
12390 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
123a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
123b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
123c0 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
123d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
123e0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
123f0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
12400 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
12410 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
12420 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
12430 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
12440 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
12450 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
12460 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
12470 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
12480 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
12490 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
124a0 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
124b0 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
124c0 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
124d0 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
124e0 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
124f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12500 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12510 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
12520 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
12530 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
12540 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
12550 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
12560 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
12570 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
12580 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
12590 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
125a0 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
125b0 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
125c0 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
125d0 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
125e0 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
125f0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
12600 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
12610 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
12620 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
12630 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
12640 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
12650 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12660 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
12670 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
12680 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
12690 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
126a0 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
126b0 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
126c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
126d0 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
126e0 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
126f0 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
12700 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
12710 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
12720 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
12730 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
12740 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
12750 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
12760 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12770 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
12780 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
12790 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
127a0 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
127b0 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
127c0 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
127d0 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
127e0 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
127f0 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12800 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
12810 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
12820 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
12830 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
12840 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
12850 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
12860 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12870 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
12880 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
12890 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
128a0 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
128b0 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
128c0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
128d0 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
128e0 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
128f0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
12900 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
12910 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
12920 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44  PI int SQLITE_CD
12930 45 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ECL sqlite3_conf
12940 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
12950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12960 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
12970 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
12980 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
12990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
129a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
129b0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
129c0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
129d0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
129e0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
129f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
12a00 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
12a10 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
12a20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12a30 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
12a40 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
12a50 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
12a60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12a70 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
12a80 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
12a90 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
12aa0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12ab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
12ac0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
12ad0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
12ae0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12af0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
12b00 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
12b10 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
12b20 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
12b30 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
12b40 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
12b50 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
12b60 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
12b70 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
12b80 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
12b90 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
12ba0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
12bb0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
12bc0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12bd0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
12be0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
12bf0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
12c00 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
12c10 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
12c20 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
12c30 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
12c40 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
12c50 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
12c60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12c70 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
12c80 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
12c90 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
12ca0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12cb0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
12cc0 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
12cd0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
12ce0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12cf0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d00 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
12d10 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
12d20 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
12d30 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
12d40 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
12d50 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12d60 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12d70 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
12d80 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
12d90 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
12da0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12db0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
12dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12dd0 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
12de0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12df0 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
12e00 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
12e10 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
12e20 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
12e30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12e40 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
12e50 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
12e60 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
12e70 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
12e80 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
12e90 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12ea0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12eb0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
12ec0 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
12ed0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
12ee0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
12ef0 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
12f00 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
12f10 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
12f20 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
12f30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
12f40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
12f50 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
12f60 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
12f70 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
12f80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12f90 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
12fa0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
12fb0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
12fc0 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
12fd0 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
12fe0 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
12ff0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13000 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
13010 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
13020 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
13030 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
13040 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
13050 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
13060 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
13070 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
13080 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
13090 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
130a0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
130b0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
130c0 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
130d0 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
130e0 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
130f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13100 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
13110 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
13120 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
13130 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
13140 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13150 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
13160 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
13170 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
13180 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
13190 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
131a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
131b0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
131c0 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
131d0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
131e0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
131f0 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
13200 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
13210 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
13220 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
13230 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
13240 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
13250 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
13260 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
13270 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
13280 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
13290 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
132a0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
132b0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
132c0 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
132d0 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
132e0 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
132f0 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
13300 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
13310 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13320 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
13330 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
13340 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
13350 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13360 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
13370 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
13380 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
13390 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
133a0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
133b0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
133c0 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
133d0 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
133e0 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
133f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13400 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
13410 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
13420 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
13430 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
13440 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
13450 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
13460 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
13470 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
13480 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
13490 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
134a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
134b0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
134c0 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
134d0 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
134e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
134f0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
13500 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
13510 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
13520 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
13530 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
13540 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
13550 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
13560 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
13570 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
13580 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
13590 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
135a0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
135b0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
135c0 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
135d0 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
135e0 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
135f0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
13600 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
13610 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
13620 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
13630 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
13640 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
13650 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
13660 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
13670 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
13680 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
13690 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
136a0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
136b0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
136c0 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
136d0 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
136e0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
136f0 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
13700 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
13710 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
13720 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
13730 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
13740 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
13750 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
13760 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
13770 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
13780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
13790 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
137a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
137b0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
137c0 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
137d0 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
137e0 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
137f0 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
13800 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
13810 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
13820 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
13830 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
13840 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
13850 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
13860 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
13870 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
13880 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
13890 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
138a0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
138b0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
138c0 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
138d0 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
138e0 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
138f0 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
13900 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
13910 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
13920 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
13930 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13940 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
13950 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
13960 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
13970 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
13980 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
13990 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
139a0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
139b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
139c0 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
139d0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
139e0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
139f0 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
13a00 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
13a10 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
13a20 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
13a30 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
13a40 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
13a50 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
13a60 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
13a70 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
13a80 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
13a90 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
13aa0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
13ab0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
13ac0 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
13ad0 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
13ae0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
13af0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
13b00 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
13b10 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
13b20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
13b30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b40 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
13b50 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
13b60 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
13b70 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
13b80 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
13b90 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
13ba0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
13bb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
13bc0 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
13bd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
13be0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
13bf0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
13c00 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
13c10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c20 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13c30 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13c40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13c50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13c60 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13c70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
13c80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13c90 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
13ca0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
13cb0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
13cc0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
13cd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13ce0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
13cf0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
13d00 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
13d10 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
13d20 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
13d30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
13d40 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
13d50 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
13d60 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
13d70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13d80 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13d90 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
13da0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
13db0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
13dc0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
13dd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13de0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
13df0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13e00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13e10 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
13e20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e30 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
13e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13e50 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13e60 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13e70 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13e80 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13e90 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13ea0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
13eb0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13ec0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
13ed0 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
13ee0 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
13ef0 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
13f00 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
13f10 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
13f20 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
13f30 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13f40 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13f50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13f60 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13f70 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13f80 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13f90 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13fa0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
13fb0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
13fc0 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
13fd0 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
13fe0 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
13ff0 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
14000 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14010 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
14020 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14030 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
14040 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14050 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
14060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
14070 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
14090 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
140a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140b0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
140c0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
140d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
140e0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
140f0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14100 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14110 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
14120 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
14130 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
14140 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
14150 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
14160 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
14170 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14180 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
14190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
141a0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
141b0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
141c0 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
141d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
141e0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
141f0 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
14200 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
14210 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
14220 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14230 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
14240 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
14250 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
14260 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
14270 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
14280 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
14290 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
142a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
142b0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
142c0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
142d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
142e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
142f0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14300 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14310 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14320 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14330 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14340 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
14350 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
14360 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
14370 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14380 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
14390 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
143a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
143b0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
143c0 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
143d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
143e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
143f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14400 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
14410 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
14420 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
14430 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
14440 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
14450 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
14460 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
14470 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
14480 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
14490 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
144a0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
144b0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
144c0 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
144d0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
144e0 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
144f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14500 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14510 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14520 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
14530 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
14540 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
14550 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14560 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
14570 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
14580 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
14590 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
145a0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
145b0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
145c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
145d0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
145e0 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
145f0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
14600 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
14610 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
14620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14630 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
14640 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14650 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
14660 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
14670 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
14680 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14690 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
146a0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
146b0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
146c0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
146d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
146e0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
146f0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
14700 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
14710 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
14720 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
14730 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14740 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
14750 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
14760 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
14770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
14780 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
14790 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
147a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
147b0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
147c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
147d0 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
147e0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
147f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14800 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14810 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14820 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
14830 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14840 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14850 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14860 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
14870 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
14880 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
14890 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
148a0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
148b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
148c0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
148d0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
148e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
148f0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14900 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
14910 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
14920 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
14930 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
14940 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14950 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
14960 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
14970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
14980 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
14990 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
149a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
149b0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
149c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
149d0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
149e0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
149f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
14a00 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14a10 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14a20 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14a30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14a40 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14a50 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14a60 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14a70 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
14a80 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
14a90 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
14aa0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
14ab0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
14ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14ad0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14ae0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14af0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14b00 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
14b10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b20 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14b30 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
14b40 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
14b50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14b60 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
14b70 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
14b80 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
14b90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14ba0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14bb0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
14bc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14bd0 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
14be0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14bf0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
14c00 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
14c10 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
14c20 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
14c30 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14c40 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14c50 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14c60 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14c70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14c80 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14c90 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
14ca0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14cb0 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
14cc0 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
14cd0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
14ce0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
14cf0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
14d00 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
14d10 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14d20 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14d30 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14d40 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14d50 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14d60 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14d70 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14d80 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
14d90 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
14da0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
14db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
14dc0 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
14dd0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
14de0 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
14df0 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
14e00 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
14e10 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
14e20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
14e30 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
14e40 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
14e50 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
14e60 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
14e70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14e80 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
14e90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14ea0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
14eb0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
14ec0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
14ed0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
14ee0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
14ef0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
14f00 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
14f10 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
14f20 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
14f30 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
14f40 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
14f50 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
14f60 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
14f70 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
14f80 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
14f90 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
14fa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
14fb0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
14fc0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
14fd0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
14fe0 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
14ff0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
15000 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
15010 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
15020 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15030 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
15040 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15050 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
15060 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
15070 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
15080 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
15090 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
150a0 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
150b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
150c0 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
150d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
150e0 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
150f0 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
15100 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
15110 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
15120 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
15130 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
15140 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
15150 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
15160 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
15170 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
15180 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
15190 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
151a0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
151b0 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
151c0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
151d0 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
151e0 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
151f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
15200 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
15210 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
15220 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
15230 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
15240 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
15250 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
15260 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
15270 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
15280 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
15290 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
152a0 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
152b0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
152c0 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
152d0 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
152e0 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
152f0 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
15300 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
15310 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15320 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15330 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
15340 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15350 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
15360 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15370 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
15380 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
15390 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
153a0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
153b0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
153c0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
153d0 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
153e0 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
153f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15400 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
15410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
15420 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15430 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
15440 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
15450 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
15460 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
15470 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
15480 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15490 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  2].** configurat
154a0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e  ion option..** ^
154b0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
154c0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
154d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
154e0 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
154f0 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
15500 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
15510 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
15520 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
15530 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
15540 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
15550 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
15560 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
15570 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
15580 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
15590 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
155a0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
155b0 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
155c0 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
155d0 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
155e0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
155f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15600 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
15610 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
15620 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
15630 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
15640 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15650 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70  PCACHE_HDRSZ] op
15660 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tion .** to [sql
15670 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
15680 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  ** ^It is harmle
15690 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
156a0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
156b0 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20  ,.** for the sz 
156c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
156d0 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65  larger than nece
156e0 73 73 61 72 79 2e 20 20 54 68 65 20 66 69 72 73  ssary.  The firs
156f0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
15700 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  ould pointer to 
15710 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
15720 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
15730 79 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20  y that.** is at 
15740 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
15750 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65   of memory, othe
15760 72 77 69 73 65 20 73 75 62 73 65 71 75 65 6e 74  rwise subsequent
15770 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
15780 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53  undefined..** ^S
15790 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
157a0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
157b0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
157c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
157d0 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
157e0 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
157f0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
15800 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
15810 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
15820 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
15830 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
15840 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
15850 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
15860 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
15870 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
15880 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
15890 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
158a0 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
158b0 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a   space.</dd>.**.
158c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
158d0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
158e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
158f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15900 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15910 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
15920 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
15930 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
15940 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
15950 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
15960 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
15970 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15980 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
15990 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
159a0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
159b0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
159c0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
159d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
159e0 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
159f0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
15a00 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15a10 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15a20 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
15a30 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
15a40 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
15a50 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
15a60 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
15a70 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
15a80 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
15a90 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
15aa0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
15ab0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
15ac0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15ad0 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
15ae0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
15af0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
15b00 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15b10 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
15b20 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
15b30 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
15b40 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
15b50 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
15b60 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
15b70 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
15b80 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
15b90 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
15ba0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
15bb0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15bc0 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
15bd0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
15be0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
15bf0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
15c00 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
15c10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15c20 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
15c30 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
15c40 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
15c50 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
15c60 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
15c70 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
15c80 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
15c90 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
15ca0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15cb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
15cc0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
15cd0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
15ce0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
15cf0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
15d00 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
15d10 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
15d20 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
15d30 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
15d40 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
15d50 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
15d60 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
15d70 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
15d80 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
15d90 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
15da0 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
15db0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
15dc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15dd0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
15de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15df0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15e00 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15e10 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
15e20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15e30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15e40 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
15e50 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
15e60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15e70 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15e80 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
15e90 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
15ea0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
15eb0 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
15ec0 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
15ed0 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
15ee0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15ef0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
15f00 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
15f10 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
15f20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
15f30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
15f40 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
15f50 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
15f60 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
15f70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
15f80 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
15f90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15fa0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
15fb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
15fc0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15fd0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
15fe0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
15ff0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
16000 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
16010 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
16020 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
16030 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
16040 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
16050 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
16060 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
16070 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16080 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
16090 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
160a0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
160b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
160c0 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
160d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
160e0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
160f0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
16100 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
16110 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16120 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
16130 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
16140 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
16150 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
16160 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
16170 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
16180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
16190 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
161a0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
161b0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
161c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
161d0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
161e0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
161f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
16200 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
16210 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
16220 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
16230 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
16240 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
16250 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
16260 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
16270 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
16280 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
16290 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
162a0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
162b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
162c0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
162d0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
162e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
162f0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
16300 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
16310 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
16320 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
16330 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16340 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16350 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
16360 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
16370 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
16380 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16390 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
163a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
163b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
163c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
163d0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
163e0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
163f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
16400 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16410 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
16420 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
16430 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
16440 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
16450 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
16460 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
16470 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
16480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16490 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
164a0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
164b0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
164c0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
164d0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
164e0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
164f0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
16500 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
16510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
16520 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
16530 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
16540 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
16550 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
16560 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
16570 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16580 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
16590 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
165a0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
165b0 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
165c0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
165d0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
165e0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
165f0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
16600 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16610 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16620 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
16630 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
16640 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16650 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16660 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
16670 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16680 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
16690 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
166a0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
166b0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
166c0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
166d0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
166e0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
166f0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
16700 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
16710 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
16720 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
16730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
16740 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
16750 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
16760 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16770 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
16780 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16790 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
167a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
167b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
167c0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
167d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
167e0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
167f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16800 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16810 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16820 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
16830 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
16840 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
16850 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16860 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
16870 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
16880 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16890 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
168a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
168b0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
168c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
168d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
168e0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
168f0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
16900 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
16910 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
16920 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
16930 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
16940 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
16950 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
16960 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
16970 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
16980 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
16990 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
169a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
169b0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
169c0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
169d0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
169e0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
169f0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
16a00 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
16a10 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
16a20 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
16a30 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
16a40 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
16a50 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
16a60 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
16a70 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
16a80 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
16a90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16aa0 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
16ab0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
16ac0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
16ad0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16ae0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
16af0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
16b00 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
16b10 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
16b20 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
16b30 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
16b40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16b50 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16b60 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
16b70 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16b80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
16b90 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
16ba0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
16bb0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
16bc0 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
16bd0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
16be0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
16bf0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
16c00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16c10 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
16c20 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
16c30 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
16c40 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
16c50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16c60 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
16c70 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
16c80 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
16c90 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
16ca0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
16cb0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
16cc0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
16cd0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
16ce0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
16cf0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
16d00 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
16d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16d20 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
16d30 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
16d40 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
16d50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
16d70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16d80 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
16d90 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16da0 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
16db0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
16dc0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
16dd0 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
16de0 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
16df0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16e00 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
16e10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
16e20 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
16e30 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16e40 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
16e50 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
16e60 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
16e70 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
16e80 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
16e90 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
16ea0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
16eb0 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
16ec0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
16ed0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
16ee0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
16ef0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
16f00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
16f10 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
16f20 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
16f30 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
16f40 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
16f50 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
16f60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
16f70 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
16f80 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
16f90 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
16fa0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
16fb0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
16fc0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
16fd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
16fe0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
16ff0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
17010 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
17020 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
17030 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
17040 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
17050 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
17060 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
17070 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
17080 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
17090 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
170a0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
170b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
170c0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
170d0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
170e0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
170f0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
17100 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17110 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
17120 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
17130 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
17140 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
17150 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
17160 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
17170 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
17180 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17190 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
171a0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
171b0 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
171c0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
171d0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
171e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
171f0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
17200 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
17210 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
17220 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
17230 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17240 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
17250 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
17260 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
17270 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
17280 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
17290 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
172a0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
172b0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
172c0 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
172d0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
172e0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
172f0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
17300 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
17310 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
17320 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
17330 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
17340 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
17350 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
17360 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
17370 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
17380 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
17390 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
173a0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
173b0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
173c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
173d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
173e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
173f0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
17400 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
17410 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17420 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
17430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17440 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
17450 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
17460 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
17470 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
17480 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
17490 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
174a0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
174b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
174c0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
174d0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
174e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
174f0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
17500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17510 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
17520 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
17530 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
17540 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
17550 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
17560 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
17570 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
17580 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
17590 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
175a0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
175b0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
175c0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
175d0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
175e0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
175f0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
17600 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
17610 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
17620 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
17630 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
17640 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
17650 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
17660 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
17670 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
17680 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
17690 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
176a0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
176b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
176c0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
176d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
176e0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
176f0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
17700 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
17710 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
17720 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
17730 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
17740 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
17750 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17760 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
17770 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
17780 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17790 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
177a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
177b0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
177c0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
177d0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
177e0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
177f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
17800 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
17810 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
17820 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
17830 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17840 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
17850 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
17860 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17870 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
17880 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
17890 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
178a0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
178b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
178c0 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
178d0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
178e0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
178f0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
17900 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
17910 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
17920 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17930 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
17940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17950 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
17960 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
17970 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
17980 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
17990 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
179a0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
179b0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
179c0 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
179d0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
179e0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
179f0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
17a00 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
17a10 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
17a20 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
17a30 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
17a40 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
17a50 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
17a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17a70 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
17a80 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
17a90 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
17aa0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
17ab0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
17ac0 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
17ad0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
17ae0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
17af0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
17b00 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
17b10 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
17b20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
17b30 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
17b40 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
17b50 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
17b60 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
17b70 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17b80 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
17b90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17ba0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
17bb0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
17bc0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
17bd0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
17be0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
17bf0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
17c00 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
17c10 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
17c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17c30 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
17c40 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17c50 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17c60 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
17c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17c80 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
17c90 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
17ca0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
17cb0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
17cc0 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
17cd0 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
17ce0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
17cf0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
17d00 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
17d10 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17d20 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
17d30 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
17d40 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
17d50 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
17d60 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
17d70 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
17d80 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
17d90 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17da0 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
17db0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17dc0 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
17dd0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
17df0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
17e00 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
17e10 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
17e20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17e30 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
17e40 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
17e50 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
17e60 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
17e70 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
17e80 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
17e90 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
17ea0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
17eb0 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
17ec0 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
17ed0 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
17ee0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
17ef0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
17f00 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
17f10 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
17f20 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
17f30 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
17f40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
17f50 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
17f60 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17f70 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
17f80 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17f90 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17fa0 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
17fb0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
17fc0 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
17fd0 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
17fe0 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
17ff0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
18000 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
18010 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
18020 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
18030 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
18040 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
18050 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
18060 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
18070 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
18080 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
18090 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
180a0 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
180b0 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
180c0 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
180d0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
180e0 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
180f0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
18100 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
18110 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
18120 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
18130 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
18140 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
18150 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
18160 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
18170 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  value..** </dl>.
18180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18190 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
181a0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
181b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
181c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
181d0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
181e0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
181f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
18200 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
18210 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
18230 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
18240 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
18250 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18270 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
18280 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
18290 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
182a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
182b0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
182c0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
182d0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
182e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
182f0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
18300 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
18310 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
18320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18330 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
18340 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
18350 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
18360 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
18370 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
18380 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
18390 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
183a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
183b0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
183c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
183d0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
183e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
183f0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
18400 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
18410 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
18420 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
18430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
18440 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
18450 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
18460 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
18470 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18480 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
18490 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
184a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
184b0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
184c0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
184d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
184e0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
184f0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
18500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18510 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
18520 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
18530 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
18540 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18550 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
18560 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
18570 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18580 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
18590 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
185a0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
185b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
185c0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
185d0 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
185e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
185f0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18600 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
18610 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
18620 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
18630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18640 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
18650 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
18660 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
18670 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18680 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
18690 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
186a0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
186b0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
186c0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
186d0 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
186e0 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
186f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18700 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
18710 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
18720 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
18730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18740 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
18750 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
18760 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
18770 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  Pma */../*.** CA
18780 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
18790 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
187a0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
187b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
187c0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
187d0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
187e0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
187f0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
18800 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
18810 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18820 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
18830 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18840 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
18850 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
18860 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
18870 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
18880 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
18890 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
188a0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
188b0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
188c0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
188d0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
188e0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
188f0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
18900 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
18910 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
18920 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
18930 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
18940 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
18950 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
18960 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
18970 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
18980 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
18990 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
189a0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
189b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
189c0 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
189d0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
189e0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
189f0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
18a00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18a10 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
18a20 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
18a30 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
18a40 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
18a50 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
18a60 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
18a70 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
18a80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18a90 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
18aa0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18ab0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
18ac0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
18ad0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
18ae0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
18af0 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
18b00 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
18b10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
18b20 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
18b30 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
18b40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18b50 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
18b60 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
18b70 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
18b80 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
18b90 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
18ba0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
18bb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
18bc0 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
18bd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
18be0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
18bf0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
18c00 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
18c10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
18c20 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
18c30 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
18c40 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
18c50 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
18c60 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
18c70 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
18c80 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
18c90 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
18ca0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
18cb0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
18cc0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
18cd0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
18ce0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
18cf0 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
18d00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
18d10 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
18d20 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
18d30 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
18d40 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
18d50 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
18d60 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
18d70 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
18d80 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
18d90 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
18da0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
18db0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
18dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
18dd0 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
18de0 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
18df0 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
18e00 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
18e10 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
18e20 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
18e30 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
18e40 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
18e50 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
18e60 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
18e70 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
18e80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
18e90 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
18ea0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
18eb0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
18ec0 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
18ed0 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
18ee0 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
18ef0 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
18f00 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
18f10 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
18f20 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
18f30 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
18f40 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18f50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18f60 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
18f70 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18f80 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18f90 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18fa0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
18fb0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
18fc0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
18fd0 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
18fe0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
18ff0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
19000 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19010 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
19020 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
19030 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
19040 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
19050 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
19060 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
19070 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
19080 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
19090 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
190a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
190b0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
190c0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
190d0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
190e0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
190f0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
19100 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
19110 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
19120 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19130 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19140 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19150 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
19160 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
19170 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
19180 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
19190 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
191a0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
191b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
191c0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
191d0 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
191e0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
191f0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
19200 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
19210 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
19220 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
19230 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19240 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19250 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19260 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19270 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19280 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19290 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
192a0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
192b0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
192c0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
192d0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
192e0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
192f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19300 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
19310 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
19320 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
19330 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
19340 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
19350 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
19360 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
19370 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19380 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19390 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
193a0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
193b0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
193c0 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
193d0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
193e0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
193f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
19400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19410 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19420 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
19430 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
19440 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19450 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19460 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
19470 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
19480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19490 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
194a0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
194b0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
194c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
194d0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
194e0 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
194f0 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f  t Codes.** METHO
19500 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
19520 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19530 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
19540 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
19550 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
19560 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
19570 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
19580 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
19590 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
195a0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
195b0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
195c0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
195d0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
195e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
195f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
19600 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
19610 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
19620 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
19630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
19640 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
19650 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19660 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
19670 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
19680 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
19690 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
196a0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
196b0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
196c0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
196d0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
196e0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
196f0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
19700 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
19710 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
19720 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
19730 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
19740 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
19750 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
19760 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
19770 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
19780 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
19790 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
197a0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
197b0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
197c0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
197d0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
197e0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
197f0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
19800 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
19810 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19820 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19830 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
19840 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
19850 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
19860 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
19870 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
19880 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
19890 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
198a0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
198b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
198c0 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
198d0 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
198e0 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
198f0 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
19900 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
19910 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
19920 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
19930 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
19940 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
19950 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
19960 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
19970 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19980 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
19990 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
199a0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
199b0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
199c0 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
199d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
199e0 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
199f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
19a00 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
19a10 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
19a20 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
19a30 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
19a40 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
19a50 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
19a60 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
19a70 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
19a80 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
19a90 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
19aa0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
19ab0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
19ac0 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
19ad0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
19ae0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
19af0 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
19b00 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
19b10 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
19b20 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
19b30 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
19b40 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
19b50 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
19b60 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
19b70 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
19b80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19b90 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
19ba0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
19bb0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
19bc0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
19bd0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
19be0 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
19bf0 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
19c00 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
19c10 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19c20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
19c30 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
19c40 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
19c50 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
19c60 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
19c70 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
19c80 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
19c90 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
19ca0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
19cb0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
19cc0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
19cd0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
19ce0 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
19cf0 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
19d00 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
19d10 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
19d20 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
19d30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19d40 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
19d50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
19d60 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
19d70 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
19d80 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
19d90 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
19da0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
19db0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
19dc0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
19dd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
19de0 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
19df0 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
19e00 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
19e10 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
19e20 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
19e30 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
19e40 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
19e50 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
19e60 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
19e70 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
19e80 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
19e90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
19ea0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19eb0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
19ec0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
19ed0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
19ee0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
19ef0 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
19f00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19f10 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
19f20 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
19f30 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
19f40 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
19f50 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
19f60 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
19f70 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
19f80 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c   [rowid]..*/.SQL
19f90 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
19fa0 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
19fb0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73  CALL sqlite3_las
19fc0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
19fd0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
19fe0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
19ff0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1a000 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a010 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a020 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a030 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a040 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a050 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1a060 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1a070 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1a080 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1a090 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a0a0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1a0b0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1a0c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a0d0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1a0e0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1a0f0 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1a100 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1a110 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1a120 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1a130 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1a140 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1a150 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1a160 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1a170 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1a180 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1a190 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1a1a0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1a1b0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1a1c0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1a1d0 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1a1e0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1a1f0 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1a200 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1a210 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1a220 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1a230 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a240 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1a250 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1a260 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1a270 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1a280 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1a290 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1a2a0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1a2b0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1a2c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a2d0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1a2e0 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1a2f0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1a300 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1a310 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1a320 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1a330 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1a340 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1a350 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1a360 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1a370 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1a380 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1a390 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a3a0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1a3b0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1a3c0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1a3d0 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1a3e0 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1a3f0 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1a400 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1a410 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a420 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1a430 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1a440 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1a450 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1a460 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1a470 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1a480 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1a490 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1a4a0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1a4b0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1a4c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1a4d0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1a4e0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1a4f0 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1a500 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1a510 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1a520 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1a530 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1a540 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1a550 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1a560 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1a570 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1a580 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1a590 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1a5a0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1a5b0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1a5c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a5d0 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1a5e0 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1a5f0 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1a600 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1a610 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1a620 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1a630 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1a640 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1a650 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1a660 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a670 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1a680 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1a690 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1a6a0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1a6b0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1a6c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1a6d0 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1a6e0 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1a6f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1a700 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1a710 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1a720 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1a730 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1a740 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1a750 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1a760 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1a770 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1a780 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1a790 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1a7a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1a7b0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1a7c0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1a7d0 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1a7e0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1a7f0 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1a800 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a810 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1a820 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1a830 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1a840 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1a850 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1a860 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1a870 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1a880 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
1a890 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
1a8a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a8b0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1a8c0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1a8d0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1a8e0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
1a8f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1a900 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1a910 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
1a920 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
1a930 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1a940 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
1a950 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
1a960 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a970 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a980 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
1a990 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a9a0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a9b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1a9c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1a9d0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  LL sqlite3_chang
1a9e0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1a9f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1aa00 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1aa10 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1aa20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1aa30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1aa40 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1aa50 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1aa60 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1aa70 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1aa80 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1aa90 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1aaa0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1aab0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1aac0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1aad0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aae0 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1aaf0 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1ab00 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1ab10 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1ab20 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1ab30 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1ab40 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1ab50 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1ab60 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1ab70 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ab80 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1ab90 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1aba0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1abb0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1abc0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1abd0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1abe0 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1abf0 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1ac00 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1ac10 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1ac20 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1ac30 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1ac40 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1ac50 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1ac60 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1ac70 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1ac80 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1ac90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1aca0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1acb0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1acc0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1acd0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1ace0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1acf0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1ad00 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1ad10 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1ad20 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1ad30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ad40 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1ad50 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1ad60 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1ad70 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1ad80 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1ad90 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1ada0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1adb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1adc0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1add0 4c 4c 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  LL sqlite3_total
1ade0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1adf0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1ae00 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1ae10 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1ae20 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ery.** METHOD: s
1ae30 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1ae40 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
1ae50 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
1ae60 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1ae70 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
1ae80 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
1ae90 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
1aea0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
1aeb0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
1aec0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
1aed0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
1aee0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
1aef0 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
1af00 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
1af10 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
1af20 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
1af30 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
1af40 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
1af50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
1af60 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1af70 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
1af80 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
1af90 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
1afa0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
1afb0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
1afc0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
1afd0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
1afe0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1aff0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1b000 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
1b010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
1b020 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
1b030 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
1b040 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
1b050 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
1b060 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
1b070 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1b080 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
1b090 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
1b0a0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
1b0b0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
1b0c0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
1b0d0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
1b0e0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
1b0f0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
1b100 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
1b110 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
1b120 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
1b130 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
1b140 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
1b150 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
1b160 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
1b170 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
1b180 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
1b190 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
1b1a0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1b1b0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1b1c0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
1b1d0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
1b1e0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
1b1f0 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
1b200 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
1b210 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1b220 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
1b230 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b240 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
1b250 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
1b260 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1b270 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1b280 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
1b290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1b2a0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
1b2b0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
1b2c0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1b2d0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1b2e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b2f0 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
1b300 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
1b310 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
1b320 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1b330 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
1b340 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
1b350 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
1b360 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1b370 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1b380 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
1b390 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1b3a0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1b3b0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
1b3c0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
1b3d0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
1b3e0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
1b3f0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
1b400 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
1b410 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1b420 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
1b430 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
1b440 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
1b450 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1b460 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
1b470 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
1b480 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
1b490 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1b4a0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1b4b0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b4c0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
1b4d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
1b4e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b4f0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
1b500 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
1b510 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
1b520 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
1b530 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
1b540 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51  ly happen..*/.SQ
1b550 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1b560 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1b570 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
1b580 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1b590 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
1b5a0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
1b5b0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
1b5c0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
1b5d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1b5e0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
1b5f0 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
1b600 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
1b610 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
1b620 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
1b630 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
1b640 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1b650 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
1b660 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
1b670 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
1b680 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
1b690 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
1b6a0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
1b6b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1b6c0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
1b6d0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
1b6e0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
1b6f0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1b700 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
1b710 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
1b720 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
1b730 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
1b740 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
1b750 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
1b760 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
1b770 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
1b780 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
1b790 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
1b7a0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
1b7b0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
1b7c0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
1b7d0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
1b7e0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
1b7f0 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
1b800 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
1b810 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
1b820 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
1b830 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
1b840 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
1b850 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
1b860 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
1b870 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
1b880 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
1b890 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
1b8a0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
1b8b0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
1b8c0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
1b8d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1b8e0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
1b8f0 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
1b900 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
1b910 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b920 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
1b930 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
1b940 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
1b950 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
1b960 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
1b970 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
1b980 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
1b990 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
1b9a0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
1b9b0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
1b9c0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
1b9d0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
1b9e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
1b9f0 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
1ba00 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
1ba10 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ba20 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
1ba30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
1ba40 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
1ba50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
1ba60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ba70 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
1ba80 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
1ba90 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
1baa0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1bab0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
1bac0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
1bad0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
1bae0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1baf0 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
1bb00 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
1bb10 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
1bb20 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1bb30 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
1bb40 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1bb50 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
1bb60 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1bb70 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1bb80 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1bb90 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1bba0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1bbb0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1bbc0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1bbd0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1bbe0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1bbf0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1bc00 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1bc10 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  *sql);.SQLITE_AP
1bc20 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1bc30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
1bc40 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1bc50 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1bc60 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1bc70 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1bc80 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1bc90 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b  BUSY Errors.** K
1bca0 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68  EYWORDS: {busy-h
1bcb0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d  andler callback}
1bcc0 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a   {busy handler}.
1bcd0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1bce0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1bcf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1bd00 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
1bd10 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
1bd20 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
1bd30 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
1bd40 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
1bd50 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
1bd60 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
1bd70 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
1bd80 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1bd90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1bda0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1bdb0 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
1bdc0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1bdd0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1bde0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
1bdf0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1be00 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1be10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
1be20 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
1be30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1be40 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
1be50 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1be60 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
1be70 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1be80 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
1be90 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1bea0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
1beb0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
1bec0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
1bed0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
1bee0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
1bef0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
1bf00 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
1bf10 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1bf20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
1bf30 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
1bf40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1bf50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1bf60 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
1bf70 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
1bf80 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
1bf90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1bfa0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
1bfb0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
1bfc0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1bfd0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
1bfe0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1bff0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1c000 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
1c010 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
1c020 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
1c030 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
1c040 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
1c050 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
1c060 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
1c070 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
1c080 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
1c090 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
1c0a0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
1c0b0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1c0c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
1c0d0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
1c0e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c0f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
1c100 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1c110 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
1c120 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
1c130 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1c140 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1c150 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1c160 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1c170 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1c180 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1c190 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1c1a0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1c1b0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1c1c0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1c1d0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1c1e0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1c1f0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1c200 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1c210 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1c220 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1c230 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1c240 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c250 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
1c260 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
1c270 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
1c280 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
1c290 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1c2a0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1c2b0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1c2c0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1c2d0 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1c2e0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1c2f0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1c300 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1c310 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1c320 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1c330 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1c340 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1c350 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1c360 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1c370 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1c380 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1c390 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1c3a0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1c3b0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1c3c0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1c3d0 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1c3e0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1c3f0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1c400 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1c410 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1c420 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1c430 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1c440 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1c450 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1c460 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1c470 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1c480 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1c490 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1c4a0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1c4b0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1c4c0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1c4d0 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1c4e0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1c4f0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1c500 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1c510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1c520 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1c530 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1c540 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1c550 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1c560 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1c570 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1c580 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c590 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1c5a0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1c5b0 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1c5c0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1c5d0 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1c5e0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1c5f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1c600 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1c610 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1c620 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1c630 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1c640 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1c650 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1c660 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1c670 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1c680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1c690 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1c6a0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1c6b0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1c6c0 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1c6d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c6e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1c6f0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1c700 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1c710 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1c720 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1c730 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1c740 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1c750 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1c760 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1c770 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1c780 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1c790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c7a0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1c7b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1c7c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1c7d0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1c7e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1c7f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1c800 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c810 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1c820 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
1c830 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1c840 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1c850 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d  usy Timeout.** M
1c860 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c870 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1c880 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
1c890 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
1c8a0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
1c8b0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
1c8c0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
1c8d0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
1c8e0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
1c8f0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
1c900 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
1c910 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
1c920 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
1c930 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1c940 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
1c950 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
1c960 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
1c970 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1c980 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1c990 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1c9a0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1c9b0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1c9c0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1c9d0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1c9e0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  USY]..**.** ^Cal
1c9f0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
1ca00 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
1ca10 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
1ca20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
1ca30 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
1ca40 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
1ca50 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1ca60 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1ca70 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
1ca80 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
1ca90 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1caa0 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67  ection] at any g
1cab0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
1cac0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
1cad0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
1cae0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
1caf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1cb00 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
1cb10 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
1cb20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
1cb30 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1cb40 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
1cb50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
1cb60 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1cb70 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eout].*/.SQLITE_
1cb80 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1cb90 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
1cba0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1cbb0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1cbc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cbd0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1cbe0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1cbf0 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1cc00 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1cc10 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1cc20 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1cc30 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1cc40 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1cc50 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1cc60 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1cc70 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1cc80 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1cc90 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1cca0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1ccb0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1ccc0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1ccd0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1cce0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ccf0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1cd00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1cd10 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1cd20 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1cd30 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1cd40 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1cd50 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1cd60 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1cd70 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1cd80 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1cd90 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1cda0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1cdb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1cdc0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1cdd0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1cde0 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1cdf0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1ce00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1ce10 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1ce20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1ce30 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1ce40 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1ce50 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1ce60 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1ce70 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1ce80 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1ce90 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1cea0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1ceb0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1cec0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1ced0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1cee0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1cef0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1cf00 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1cf10 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1cf20 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1cf30 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1cf40 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1cf50 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1cf60 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1cf70 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1cf80 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1cf90 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1cfa0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1cfb0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1cfc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1cfd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1cfe0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1cff0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1d000 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1d010 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1d020 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1d030 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1d040 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1d050 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1d060 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1d070 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1d080 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1d090 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1d0a0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1d0b0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1d0c0 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1d0d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1d0e0 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1d0f0 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1d100 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1d110 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1d120 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1d130 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1d140 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1d150 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1d160 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1d170 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1d180 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1d190 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1d1a0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1d1b0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1d1c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d1d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1d1e0 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1d1f0 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1d200 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1d210 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1d220 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1d230 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1d240 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1d250 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1d260 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1d270 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1d280 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1d290 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1d2a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1d2b0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1d2c0 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1d2d0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1d2e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1d2f0 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1d300 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d310 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1d320 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d330 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1d340 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d350 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1d360 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1d370 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1d380 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1d390 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1d3a0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1d3b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d3c0 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1d3d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d3e0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1d3f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d400 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1d410 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1d420 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1d430 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1d440 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1d450 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d460 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1d470 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1d480 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1d490 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1d4a0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1d4b0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1d4c0 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1d4d0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1d4e0 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1d4f0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1d500 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1d510 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d520 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1d530 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1d540 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1d550 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1d560 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1d570 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1d580 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1d590 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1d5a0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1d5b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1d5c0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1d5d0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1d5e0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1d5f0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1d600 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1d610 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1d620 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1d630 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1d640 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1d650 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1d660 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d670 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1d680 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1d690 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d6a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1d6b0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1d6c0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1d6d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d6e0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1d6f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1d700 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1d710 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1d720 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1d730 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1d740 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1d750 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1d760 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1d770 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1d780 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1d790 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1d7a0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1d7b0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1d7c0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1d7d0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1d7e0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1d7f0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1d800 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d810 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1d820 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1d830 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d840 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1d850 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1d860 4c 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  LL sqlite3_get_t
1d870 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1d880 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1d890 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1d8a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1d8b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1d8c0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1d8d0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1d8e0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1d8f0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1d900 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1d910 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1d920 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1d930 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1d940 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1d950 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1d960 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1d970 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1d980 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d990 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1d9a0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1d9b0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1d9c0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1d9d0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
1d9e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72  DCALL sqlite3_fr
1d9f0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1da00 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1da10 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1da20 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1da30 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1da40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1da50 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1da60 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1da70 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1da80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1da90 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1daa0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1dab0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1dac0 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1dad0 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1dae0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1daf0 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1db00 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1db10 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1db20 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1db30 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1db40 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1db50 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1db60 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1db70 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1db80 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1db90 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1dba0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1dbb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1dbc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1dbd0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1dbe0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1dbf0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1dc00 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1dc10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1dc20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dc30 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1dc40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1dc50 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1dc60 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1dc70 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1dc80 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1dc90 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1dca0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1dcb0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1dcc0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1dcd0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1dce0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1dcf0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1dd00 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1dd10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1dd20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1dd30 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1dd40 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1dd50 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1dd60 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1dd70 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1dd80 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1dd90 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1dda0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1ddb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1ddc0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1ddd0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1dde0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1ddf0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1de00 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1de10 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1de20 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1de30 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1de40 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1de50 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1de60 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1de70 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1de80 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1de90 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1dea0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1deb0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1dec0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1ded0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1dee0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1def0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1df00 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1df10 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1df20 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1df30 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1df40 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1df50 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1df60 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1df70 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1df80 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1df90 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1dfa0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1dfb0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1dfc0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1dfd0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1dfe0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1dff0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1e000 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1e010 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1e020 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1e030 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1e040 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1e050 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1e060 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1e070 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1e080 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1e090 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1e0a0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1e0b0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1e0c0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1e0d0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1e0e0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1e0f0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1e100 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1e110 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1e120 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1e130 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1e140 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1e150 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1e160 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1e170 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1e180 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1e190 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1e1a0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1e1b0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1e1c0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1e1d0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1e1e0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1e1f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1e200 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1e210 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1e220 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1e230 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1e240 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1e250 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1e260 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1e270 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1e280 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1e290 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1e2a0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1e2b0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1e2c0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1e2d0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1e2e0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1e2f0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1e300 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1e310 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1e320 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1e330 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1e340 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1e350 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1e360 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1e370 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1e380 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1e390 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1e3a0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1e3b0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1e3c0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1e3d0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1e3e0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1e3f0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1e400 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e410 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e420 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1e430 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e440 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1e450 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e460 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1e470 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1e480 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1e490 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e4a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e4b0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e4c0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e4d0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e4e0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1e4f0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e500 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e510 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e520 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e530 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e540 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e550 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1e560 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1e570 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1e580 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1e590 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1e5a0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1e5b0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1e5c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e5d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e5e0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e5f0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e600 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1e610 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1e620 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e630 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1e640 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1e650 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1e660 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1e670 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1e680 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1e690 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e6a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e6b0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e6c0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1e6d0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1e6e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e6f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e700 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1e710 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1e720 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1e730 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1e740 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1e750 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1e760 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1e770 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1e780 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1e790 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1e7a0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e7b0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1e7c0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1e7d0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1e7e0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1e7f0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1e800 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1e810 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e820 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1e830 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1e840 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1e850 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1e860 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1e870 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1e880 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1e890 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1e8a0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1e8b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e8c0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e8d0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e8e0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e8f0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1e900 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e910 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e920 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e930 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e940 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e950 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e960 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1e970 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1e980 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1e990 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1e9a0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1e9b0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1e9c0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1e9d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e9e0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1e9f0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1ea00 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1ea10 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1ea20 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1ea30 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1ea40 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1ea50 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1ea60 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1ea70 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1ea80 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1ea90 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1eaa0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1eab0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1eac0 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1ead0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1eae0 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1eaf0 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1eb00 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1eb10 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1eb20 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1eb30 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1eb40 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1eb50 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1eb60 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1eb70 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1eb80 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1eb90 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1eba0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1ebb0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1ebc0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1ebd0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1ebe0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1ebf0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c  string.)^.*/.SQL
1ec00 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1ec10 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
1ec20 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1ec30 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c   char*,...);.SQL
1ec40 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51  ITE_API char *SQ
1ec50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1ec60 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1ec70 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1ec80 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  st);.SQLITE_API 
1ec90 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45  char *SQLITE_CDE
1eca0 43 4c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  CL sqlite3_snpri
1ecb0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1ecc0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
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 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ecf0 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1ed00 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1ed10 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1ed20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ed30 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1ed40 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1ed50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1ed60 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1ed70 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1ed80 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1ed90 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1eda0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1edb0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1edc0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1edd0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1ede0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1edf0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1ee00 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1ee10 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1ee20 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1ee30 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1ee40 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1ee50 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1ee60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1ee70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ee80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1ee90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1eea0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1eeb0 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1eec0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1eed0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1eee0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1eef0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ef00 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1ef10 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1ef20 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1ef30 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1ef40 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1ef50 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1ef60 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1ef70 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1ef80 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1ef90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1efa0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1efb0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1efc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1efd0 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e  lloc64(N) routin
1efe0 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b  e works just lik
1eff0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  e.** sqlite3_mal
1f000 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68  loc(N) except th
1f010 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67  at N is an unsig
1f020 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ned 64-bit integ
1f030 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1f040 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74   a signed 32-bit
1f050 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1f060 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1f070 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1f080 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1f090 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1f0a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f0b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1f0c0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1f0d0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1f0e0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1f0f0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1f100 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1f110 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1f120 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1f130 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1f140 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1f150 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1f160 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1f170 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1f180 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1f190 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1f1a0 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1f1b0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1f1c0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1f1d0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1f1e0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1f1f0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1f200 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1f210 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1f220 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1f230 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1f240 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1f250 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1f260 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1f270 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1f280 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1f290 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1f2a0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1f2b0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1f2c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1f2d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1f2e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f2f0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
1f300 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f310 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  ,N) interface at
1f320 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1f330 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1f340 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20  ry allocation X 
1f350 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1f360 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
1f370 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
1f380 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1f390 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e  c(X,N).** is a N
1f3a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1f3b0 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1f3c0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1f3d0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1f3e0 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e  _malloc(N)..** ^
1f3f0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
1f400 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1f410 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65  alloc(X,N) is ze
1f420 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1f430 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1f440 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1f450 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1f460 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1f470 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  ee(X)..** ^sqlit
1f480 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1f490 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1f4a0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1f4b0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1f4c0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1f4d0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1f4e0 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
1f4f0 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61  memory is availa
1f500 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1f510 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1f520 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f530 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1f540 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1f550 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f560 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1f570 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1f580 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1f590 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1f5a0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e  _realloc(X,N) an
1f5b0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1f5c0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1f5d0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1f5e0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1f5f0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  urns NULL and N 
1f600 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
1f610 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61  n the.** prior a
1f620 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74  llocation is not
1f630 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1f640 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1f650 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66  oc64(X,N) interf
1f660 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73  aces works the s
1f670 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
1f680 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65  3_realloc(X,N) e
1f690 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1f6a0 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
1f6b0 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  d integer instea
1f6c0 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74  d.** of a 32-bit
1f6d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e   signed integer.
1f6e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20  .**.** ^If X is 
1f6f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1f700 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  ion previously o
1f710 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1f720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a  ite3_malloc(),.*
1f730 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f740 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  64(), sqlite3_re
1f750 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69  alloc(), or sqli
1f760 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c  te3_realloc64(),
1f770 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1f780 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1f790 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1f7a0 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  at memory alloca
1f7b0 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a  tion in bytes..*
1f7c0 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
1f7d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1f7e0 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20  _msize(X) might 
1f7f0 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
1f800 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
1f810 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20  bytes requested 
1f820 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63  when X was alloc
1f830 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20  ated.  ^If X is 
1f840 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1f850 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1f860 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1f870 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e  zero.  If X poin
1f880 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20  ts to something 
1f890 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  that is not.** t
1f8a0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1f8b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f8c0 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e  n, or if it poin
1f8d0 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79  ts to a formerly
1f8e0 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79  .** valid memory
1f8f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74   allocation that
1f900 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72   has now been fr
1f910 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  eed, then the be
1f920 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c  havior.** of sql
1f930 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73  ite3_msize(X) is
1f940 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1f950 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e  ossibly harmful.
1f960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1f970 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1f980 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1f990 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f9a0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1f9b0 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73  alloc64(), and s
1f9c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f9d0 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1f9e0 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1f9f0 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1fa00 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1fa10 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1fa20 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1fa30 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1fa40 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1fa50 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1fa60 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1fa70 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1fa80 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1fa90 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1faa0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1fab0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1fac0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1fad0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1fae0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1faf0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1fb00 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1fb10 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1fb20 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1fb30 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1fb40 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1fb50 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1fb60 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1fb70 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1fb80 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1fb90 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1fba0 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1fbb0 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1fbc0 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1fbd0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1fbe0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1fbf0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1fc00 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1fc10 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1fc20 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1fc30 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1fc40 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1fc50 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1fc60 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1fc70 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1fc80 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1fc90 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1fca0 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1fcb0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1fcc0 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1fcd0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1fce0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1fcf0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1fd00 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1fd10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1fd20 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1fd30 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1fd40 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1fd50 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1fd60 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1fd70 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1fd80 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1fd90 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1fda0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1fdb0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1fdc0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1fdd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1fde0 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1fdf0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1fe00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1fe10 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1fe20 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1fe30 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1fe40 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1fe50 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1fe60 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1fe70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1fe80 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1fe90 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1fea0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1feb0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1fec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1fed0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
1fee0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
1fef0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c  CALL sqlite3_mal
1ff00 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69  loc64(sqlite3_ui
1ff10 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
1ff20 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
1ff30 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72  TDCALL sqlite3_r
1ff40 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1ff50 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1ff60 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1ff70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ALL sqlite3_real
1ff80 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1ff90 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51  ite3_uint64);.SQ
1ffa0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1ffb0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1ffc0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1ffd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1ffe0 69 74 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49  ite3_uint64 SQLI
1fff0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
20000 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
20010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20020 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
20030 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
20040 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
20050 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
20060 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
20070 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
20080 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
20090 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
200a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
200b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
200c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
200d0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
200e0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
200f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
20100 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
20110 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
20120 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
20130 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
20140 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20150 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
20160 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
20170 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
20180 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
20190 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
201a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
201b0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
201c0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
201d0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
201e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
201f0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
20200 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
20210 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
20220 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
20230 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
20240 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20250 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
20260 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20270 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
20280 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
20290 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
202a0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
202b0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
202c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
202d0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
202e0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
202f0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
20300 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
20310 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
20320 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20330 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
20340 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
20350 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
20360 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
20370 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
20380 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
20390 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
203a0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
203b0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
203c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
203d0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
203e0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
203f0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
20400 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20410 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
20420 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
20430 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
20440 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
20450 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
20460 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
20470 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d  CALL sqlite3_mem
20480 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
20490 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
204a0 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
204b0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
204c0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
204d0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
204e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
204f0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
20500 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
20510 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
20520 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
20530 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
20540 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
20550 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
20560 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
20570 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
20580 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
20590 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
205a0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
205b0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
205c0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
205d0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
205e0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
205f0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
20600 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
20610 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
20620 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
20630 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
20640 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
20650 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
20660 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
20670 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
20680 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
20690 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
206a0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
206b0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
206c0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
206d0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61  ..** ^The P para
206e0 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e  meter can be a N
206f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20700 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ** ^If this rout
20710 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ine has not been
20720 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c   previously call
20730 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65  ed or if the pre
20740 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61  vious.** call ha
20750 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e  d N less than on
20760 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e or a NULL poin
20770 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20  ter for P, then 
20780 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73  the PRNG is.** s
20790 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
207a0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20  omness obtained 
207b0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
207c0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a  ness method of.*
207d0 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  * the default [s
207e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
207f0 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
20800 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
20810 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
20820 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
20830 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d  re and a.** non-
20840 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20  NULL P then the 
20850 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
20860 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
20870 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
20880 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
20890 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
208a0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
208b0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
208c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
208d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
208e0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
208f0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
20900 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
20910 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
20920 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
20930 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
20940 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
20950 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
20960 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
20970 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20980 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
20990 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
209a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
209b0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
209c0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
209d0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
209e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
209f0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
20a00 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
20a10 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
20a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20a30 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
20a40 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
20a50 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
20a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20a70 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
20a80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20a90 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
20aa0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
20ab0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
20ac0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
20ad0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
20ae0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
20af0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
20b00 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
20b10 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20b20 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
20b30 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
20b40 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
20b50 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20b60 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
20b70 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
20b80 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
20b90 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
20ba0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
20bb0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
20bc0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
20bd0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
20be0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
20bf0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
20c00 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
20c10 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
20c20 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
20c30 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
20c40 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
20c50 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
20c60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20c70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20c80 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
20c90 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20ca0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
20cb0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
20cc0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
20cd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
20ce0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
20cf0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
20d00 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
20d10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
20d20 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
20d30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
20d40 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
20d50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20d60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
20d70 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
20d80 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
20d90 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
20da0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20db0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
20dc0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
20dd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20de0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
20df0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
20e00 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
20e10 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
20e20 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
20e30 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
20e40 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
20e50 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
20e60 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
20e70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
20e80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20e90 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
20ea0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
20eb0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
20ec0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20ed0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
20ee0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
20ef0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
20f00 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
20f10 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
20f20 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
20f30 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
20f40 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
20f50 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
20f60 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
20f70 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
20f80 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
20f90 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
20fa0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
20fb0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
20fc0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
20fd0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
20fe0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
20ff0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21000 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
21010 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
21020 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
21030 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
21040 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21050 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
21060 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
21070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21080 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
21090 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
210a0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
210b0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
210c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
210d0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
210e0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
210f0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
21100 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
21110 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
21120 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
21130 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
21140 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
21150 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
21160 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
21170 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
21180 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
21190 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
211a0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
211b0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
211c0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
211d0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
211e0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
211f0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
21200 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
21210 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
21220 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
21230 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
21240 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
21250 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
21260 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
21270 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
21280 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
21290 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
212a0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
212b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
212c0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
212d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
212e0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
212f0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
21300 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
21310 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
21320 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
21330 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
21340 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
21350 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
21360 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
21370 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
21380 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
21390 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
213a0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
213b0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
213c0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
213d0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
213e0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
213f0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21400 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21410 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21420 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
21430 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
21440 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
21450 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
21460 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
21470 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
21480 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
21490 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
214a0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
214b0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
214c0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
214d0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
214e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
214f0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21500 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21510 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21520 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
21530 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
21540 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
21550 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
21560 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
21570 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
21580 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
21590 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
215a0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
215b0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
215c0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
215d0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
215e0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
215f0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21600 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21610 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21630 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
21640 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
21650 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21660 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
21670 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
21680 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
21690 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
216a0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
216b0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
216c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
216d0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
216e0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
216f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21700 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21710 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21720 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21730 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21740 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21750 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
21760 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
21770 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
21780 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
21790 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
217a0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
217b0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
217c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
217d0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
217e0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
217f0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21800 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21820 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21830 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
21840 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21850 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
21860 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
21870 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
21880 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
21890 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
218a0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
218b0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
218c0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
218d0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
218e0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
218f0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
21900 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21910 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
21920 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
21930 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21940 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
21950 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
21960 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
21970 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
21980 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
21990 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
219a0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
219b0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
219c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
219d0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
219e0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
219f0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
21a00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21a10 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
21a20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
21a30 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
21a40 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
21a50 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
21a60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
21a70 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
21a80 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
21a90 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
21aa0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
21ab0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
21ac0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21ad0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21ae0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
21af0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
21b00 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
21b10 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21b20 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
21b30 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21b40 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21b50 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
21b60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
21b70 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
21b80 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
21b90 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
21ba0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
21bb0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
21bc0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
21bd0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
21be0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
21bf0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
21c00 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
21c10 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
21c20 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
21c30 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
21c40 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21c50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
21c60 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
21c70 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
21c80 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
21c90 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
21ca0 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
21cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
21cc0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
21cd0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
21ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
21cf0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
21d00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
21d10 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
21d20 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
21d30 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
21d40 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
21d50 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
21d60 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
21d70 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
21d80 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
21d90 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
21da0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21db0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21dc0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
21dd0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
21de0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
21df0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
21e00 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
21e10 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
21e20 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
21e30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
21e40 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
21e50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
21e60 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
21e70 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
21e80 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
21e90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
21ea0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
21eb0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
21ec0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
21ed0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
21ee0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
21ef0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
21f00 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
21f10 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
21f20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
21f30 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
21f40 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
21f50 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
21f60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21f70 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
21f80 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
21f90 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
21fa0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
21fb0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
21fc0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
21fd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
21fe0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
21ff0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
22000 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
22010 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
22020 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
22030 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
22040 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
22050 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
22060 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
22070 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
22080 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22090 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
220a0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
220b0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
220c0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
220d0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
220e0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
220f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
22100 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
22110 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
22120 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
22130 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
22140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22150 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22160 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
22170 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
22180 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
22190 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
221a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
221b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
221c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
221d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
221e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
221f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
22200 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22210 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22220 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22230 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22240 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
22250 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
22260 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22270 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22280 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22290 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
222a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
222b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
222c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
222d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
222e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
222f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22300 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22310 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22320 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22330 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
22340 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22350 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22360 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22370 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
22380 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
22390 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
223a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
223b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
223c0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
223d0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
223e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
223f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22410 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
22420 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
22430 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22440 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22460 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
22470 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
22480 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22490 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
224a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
224b0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
224c0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
224d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
224e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
224f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22500 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
22510 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
22520 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22530 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22550 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
22560 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
22570 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22580 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22590 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
225a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
225b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
225c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
225d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
225e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
225f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
22600 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
22610 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22620 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22630 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22640 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
22650 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
22660 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22670 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22680 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
22690 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
226a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
226b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
226c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
226d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
226e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
226f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22700 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22710 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22720 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
22730 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
22740 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
22750 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
22760 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
22770 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
22780 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
22790 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
227a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
227b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
227c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
227d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
227e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
227f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22800 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22810 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
22820 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
22830 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
22840 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22860 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
22870 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
22880 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22890 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
228a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
228b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
228c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
228d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
228e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
228f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22900 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
22910 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
22920 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
22930 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22950 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
22960 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
22970 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
22980 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
229a0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
229b0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
229c0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
229d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
229e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
229f0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
22a00 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
22a10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22a20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22a30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22a40 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
22a50 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
22a60 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22a70 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22a90 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
22aa0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
22ab0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
22ac0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22ad0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
22ae0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
22af0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
22b00 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
22b10 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
22b20 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
22b30 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
22b40 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22b50 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
22b60 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
22b70 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
22b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
22b90 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
22ba0 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
22bb0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
22bc0 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
22bd0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22be0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22bf0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
22c00 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
22c10 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
22c20 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
22c30 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
22c40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22c50 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
22c60 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
22c70 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
22c80 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
22c90 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
22ca0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
22cb0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
22cc0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
22cd0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
22ce0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
22cf0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
22d00 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
22d10 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
22d20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
22d30 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
22d40 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
22d50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
22d60 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
22d70 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
22d80 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
22d90 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
22da0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
22db0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
22dc0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
22dd0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
22de0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
22df0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
22e00 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
22e10 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
22e20 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
22e30 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
22e40 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
22e50 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
22e60 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
22e70 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
22e80 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
22e90 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
22ea0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
22eb0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
22ec0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
22ed0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
22ee0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
22ef0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
22f00 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
22f10 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
22f20 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
22f30 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
22f40 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
22f50 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
22f60 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
22f70 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
22f80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
22f90 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
22fa0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
22fb0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
22fc0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
22fd0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
22fe0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
22ff0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
23000 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
23010 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
23020 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
23030 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
23040 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
23050 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
23060 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
23070 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
23080 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
23090 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
230a0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
230b0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
230c0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
230d0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
230e0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
230f0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
23100 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
23110 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
23120 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
23130 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
23140 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
23150 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
23160 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
23170 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
23180 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
23190 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
231a0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
231b0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
231c0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
231d0 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
231e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
231f0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23200 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
23210 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
23220 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
23230 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
23240 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
23250 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
23260 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
23270 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
23280 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
23290 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
232a0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
232b0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
232c0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
232d0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
232e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
232f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
23300 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
23310 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
23320 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
23330 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
23340 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
23350 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
23360 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
23370 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
23380 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
23390 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
233a0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
233b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
233c0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
233d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
233e0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
233f0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
23400 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
23410 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
23420 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
23430 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
23440 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
23450 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
23460 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
23470 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
23480 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
23490 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
234a0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
234b0 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
234c0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
234d0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
234e0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
234f0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
23500 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
23510 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
23520 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
23530 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
23540 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
23550 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
23560 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
23570 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
23580 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
23590 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
235a0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
235b0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
235c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
235d0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
235e0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
235f0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
23600 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
23610 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
23620 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
23630 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23640 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
23650 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
23660 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
23670 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
23680 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
23690 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
236a0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
236b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
236c0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
236d0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
236e0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
236f0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
23700 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
23710 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
23720 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
23730 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
23740 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
23750 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23760 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
23770 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
23780 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
23790 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
237a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
237b0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
237c0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
237d0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
237e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
237f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
23800 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
23810 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
23820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
23830 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
23840 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
23850 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
23860 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
23870 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
23880 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  ALL sqlite3_prog
23890 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
238a0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
238b0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
238c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
238d0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
238e0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
238f0 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55  ction.** CONSTRU
23900 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  CTOR: sqlite3.**
23910 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
23920 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
23930 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
23940 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
23950 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
23960 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
23970 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
23980 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
23990 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
239a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
239b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
239c0 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
239d0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
239e0 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
239f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
23a00 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
23a10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23a20 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
23a30 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
23a40 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
23a50 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
23a60 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
23a70 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
23a80 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
23a90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
23aa0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
23ab0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
23ac0 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
23ad0 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
23ae0 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
23af0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
23b00 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
23b10 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
23b20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
23b30 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
23b40 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
23b50 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
23b60 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
23b70 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
23b80 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
23b90 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
23ba0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
23bb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
23bc0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
23bd0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
23be0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
23bf0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
23c00 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
23c10 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
23c20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
23c30 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
23c40 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
23c50 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
23c60 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
23c70 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
23c80 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f  will be UTF-8 fo
23c90 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61  r databases crea
23ca0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c  ted using.** sql
23cb0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
23cc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23cd0 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
23ce0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74  encoding for dat
23cf0 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65  abases.** create
23d00 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
23d10 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65  open16() will be
23d20 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
23d30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
23d40 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
23d50 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
23d60 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
23d70 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
23d80 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
23d90 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
23da0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23db0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
23dc0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
23dd0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
23de0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
23df0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
23e00 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
23e10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23e20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
23e30 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
23e40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
23e50 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
23e60 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
23e70 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
23e80 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
23e90 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
23ea0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
23eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
23ec0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
23ed0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
23ee0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
23ef0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
23f00 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
23f10 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
23f20 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
23f30 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
23f40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
23f50 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
23f60 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
23f70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
23f80 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
23f90 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23fa0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
23fb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23fc0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
23fd0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
23fe0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
23ff0 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
24000 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24010 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
24020 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
24030 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
24040 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
24050 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
24060 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
24070 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
24080 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
24090 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
240a0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
240b0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
240c0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
240d0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
240e0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
240f0 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
24100 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
24110 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
24120 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
24130 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
24140 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
24150 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
24160 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
24170 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
24180 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
24190 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
241a0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
241b0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
241c0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
241d0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
241e0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
241f0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
24200 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
24210 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
24220 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
24230 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
24240 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
24250 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
24260 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
24270 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
24280 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
24290 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
242a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
242b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
242c0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
242d0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
242e0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
242f0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
24300 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
24310 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24320 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
24330 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
24340 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
24350 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
24360 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
24370 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
24380 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
24390 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
243a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
243b0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
243c0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
243d0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
243e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
243f0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
24400 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
24410 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
24420 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
24430 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
24440 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
24450 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
24460 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
24470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24480 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
24490 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
244a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
244b0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
244c0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
244d0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
244e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
244f0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
24500 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24510 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
24520 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
24530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24540 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
24550 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
24560 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
24570 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
24580 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
24590 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
245a0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
245b0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
245c0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
245d0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
245e0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
245f0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
24600 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24610 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
24620 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
24630 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
24640 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
24650 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
24660 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
24670 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
24680 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
24690 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
246a0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
246b0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
246c0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
246d0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
246e0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
246f0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
24700 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
24710 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
24720 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
24730 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
24740 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
24750 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
24760 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
24770 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
24780 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
24790 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
247a0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
247b0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
247c0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
247d0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
247e0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
247f0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
24800 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
24810 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
24820 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
24830 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
24840 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
24850 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
24860 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
24870 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
24880 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
24890 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
248a0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
248b0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
248c0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
248d0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
248e0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
248f0 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
24900 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
24910 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
24920 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
24930 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
24940 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
24950 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
24960 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
24970 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
24980 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
24990 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
249a0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
249b0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
249c0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
249d0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
249e0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
249f0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
24a00 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
24a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
24a20 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
24a30 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
24a40 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
24a50 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
24a60 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
24a70 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
24a80 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
24a90 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
24aa0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
24ab0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
24ac0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
24ad0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
24ae0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
24af0 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
24b00 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
24b10 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
24b20 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
24b30 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
24b40 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
24b50 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
24b60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
24b70 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
24b80 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
24b90 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
24ba0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
24bb0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
24bc0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
24bd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
24be0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
24bf0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
24c00 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
24c10 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
24c20 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
24c30 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
24c40 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24c50 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
24c60 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
24c70 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
24c80 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
24c90 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
24ca0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
24cb0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
24cc0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
24cd0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
24ce0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
24cf0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
24d00 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
24d10 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
24d20 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
24d30 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
24d40 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
24d50 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
24d60 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
24d70 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
24d80 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
24d90 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
24da0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
24db0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
24dc0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
24dd0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
24de0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
24df0 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
24e00 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
24e10 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
24e20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
24e30 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
24e40 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
24e50 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
24e60 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
24e70 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
24e80 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
24e90 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
24ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
24eb0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
24ec0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
24ed0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
24ee0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
24ef0 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
24f00 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
24f10 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
24f20 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
24f30 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
24f40 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
24f50 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
24f60 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
24f70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
24f80 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
24f90 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
24fa0 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
24fb0 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
24fc0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
24fd0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
24fe0 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
24ff0 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
25000 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
25010 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
25020 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
25030 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
25040 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
25050 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
25060 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
25070 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
25080 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
25090 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
250a0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
250b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
250c0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
250d0 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
250e0 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
250f0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
25100 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25110 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25120 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
25130 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
25140 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
25150 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
25160 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
25170 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
25180 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
25190 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
251a0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
251b0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
251c0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
251d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
251e0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
251f0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
25200 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
25210 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
25220 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
25230 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
25240 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
25250 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
25260 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
25270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25280 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
25290 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
252a0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
252b0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
252c0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
252d0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
252e0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
252f0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
25300 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
25310 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25320 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25330 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
25340 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
25350 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
25360 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
25370 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
25380 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
25390 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
253a0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
253b0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
253c0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
253d0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
253e0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
253f0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
25400 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25410 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
25420 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
25430 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
25440 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
25450 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
25460 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
25470 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
25480 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
25490 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
254a0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
254b0 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
254c0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
254d0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
254e0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
254f0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
25500 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
25510 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
25520 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25530 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
25540 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
25550 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
25560 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
25570 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
25580 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
25590 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
255a0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
255b0 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
255c0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
255d0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
255e0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
255f0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
25600 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
25610 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
25620 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
25630 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
25640 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
25650 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
25660 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
25670 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
25680 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
25690 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
256a0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
256b0 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
256c0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
256d0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
256e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
256f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25700 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
25710 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
25720 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
25730 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
25740 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
25750 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
25760 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
25770 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
25780 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25790 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
257a0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
257b0 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
257c0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
257d0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
257e0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
257f0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
25800 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
25810 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
25820 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
25830 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25840 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
25850 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
25860 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
25870 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25880 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
25890 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
258a0 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
258b0 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
258c0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
258d0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
258e0 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
258f0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
25900 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25910 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
25920 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
25930 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
25940 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
25950 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
25960 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
25970 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
25980 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
25990 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
259a0 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
259b0 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
259c0 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
259d0 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
259e0 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
259f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
25a00 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
25a10 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
25a20 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
25a30 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
25a40 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
25a50 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
25a60 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
25a70 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
25a80 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
25a90 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
25aa0 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
25ab0 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
25ac0 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
25ad0 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
25ae0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
25af0 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
25b00 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
25b10 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
25b20 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
25b30 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
25b40 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
25b50 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
25b60 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
25b70 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
25b80 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
25b90 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
25ba0 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
25bb0 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
25bc0 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
25bd0 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
25be0 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
25bf0 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
25c00 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
25c10 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
25c20 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
25c30 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
25c40 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
25c50 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
25c60 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
25c70 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
25c80 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
25c90 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
25ca0 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
25cb0 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
25cc0 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
25cd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
25ce0 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
25cf0 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
25d00 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
25d10 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
25d20 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
25d30 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
25d40 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
25d50 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
25d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
25d70 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
25d80 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
25d90 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
25da0 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
25db0 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
25dc0 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
25dd0 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
25de0 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
25df0 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
25e00 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
25e10 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
25e20 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
25e30 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
25e40 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
25e50 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
25e60 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
25e70 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
25e80 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
25e90 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
25ea0 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
25eb0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
25ec0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25ed0 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
25ee0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
25ef0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
25f00 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
25f10 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
25f20 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
25f30 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
25f40 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
25f50 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
25f60 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
25f70 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
25f80 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
25f90 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
25fa0 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
25fb0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
25fc0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
25fd0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
25fe0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
25ff0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
26000 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
26010 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
26020 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
26030 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
26040 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
26050 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
26060 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
26070 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
26080 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
26090 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
260a0 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
260b0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
260c0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
260d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
260e0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
260f0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
26100 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
26110 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
26120 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
26130 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
26140 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
26150 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
26160 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
26170 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
26180 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
26190 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
261a0 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
261b0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
261c0 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
261d0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
261e0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
261f0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
26200 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
26210 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
26220 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
26230 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
26240 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
26250 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
26260 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
26270 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
26280 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
26290 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
262a0 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
262b0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
262c0 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
262d0 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
262e0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
262f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
26300 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
26310 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
26320 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
26330 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
26340 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
26350 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
26360 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
26370 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
26380 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
26390 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
263a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
263b0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
263c0 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
263d0 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
263e0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
263f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26400 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
26410 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
26420 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
26430 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
26440 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
26450 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
26460 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
26470 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
26480 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
26490 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
264a0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
264b0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
264c0 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
264d0 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
264e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
264f0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
26500 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
26510 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
26520 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
26530 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
26540 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
26550 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
26560 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
26570 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
26580 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
26590 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
265a0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
265b0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
265c0 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
265d0 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
265e0 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
265f0 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
26600 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
26610 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
26620 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
26630 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
26640 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
26650 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
26660 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
26670 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
26680 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
26690 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
266a0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
266b0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
266c0 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
266d0 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
266e0 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
266f0 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
26700 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
26710 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
26720 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
26730 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
26740 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
26750 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
26760 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
26770 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
26780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26790 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
267a0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
267b0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
267c0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
267d0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
267e0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
267f0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
26800 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
26810 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
26820 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
26830 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
26840 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26850 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26860 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
26870 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
26880 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
26890 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
268a0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
268b0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
268c0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
268d0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
268e0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
268f0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
26900 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
26910 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
26920 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
26930 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
26940 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
26950 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
26960 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tory].*/.SQLITE_
26970 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
26980 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
26990 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
269a0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
269b0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
269c0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
269d0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
269e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
269f0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
26a00 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
26a10 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
26a20 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70  DCALL sqlite3_op
26a30 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
26a40 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
26a50 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
26a60 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
26a70 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26a80 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26a90 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26aa0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
26ab0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
26ac0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
26ad0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
26ae0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
26af0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
26b00 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
26b10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
26b20 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
26b30 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26b40 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
26b50 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
26b60 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
26b70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
26b80 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
26b90 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
26ba0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
26bb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
26bc0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
26bd0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
26be0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
26bf0 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
26c00 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
26c10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
26c20 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
26c30 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
26c40 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
26c50 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
26c60 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
26c70 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
26c80 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
26c90 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
26ca0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
26cb0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
26cc0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
26cd0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
26ce0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
26cf0 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
26d00 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
26d10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
26d20 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
26d30 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
26d40 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
26d50 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
26d60 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
26d70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
26d80 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
26d90 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
26da0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
26db0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
26dc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26dd0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
26de0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
26df0 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
26e00 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
26e10 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
26e20 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
26e30 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
26e40 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
26e50 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
26e60 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
26e70 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
26e80 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
26e90 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
26ea0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
26eb0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
26ec0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
26ed0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
26ee0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
26ef0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
26f00 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
26f10 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
26f20 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
26f30 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
26f40 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
26f50 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
26f60 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
26f70 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
26f80 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
26f90 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
26fa0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
26fb0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
26fc0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26fd0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
26fe0 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
26ff0 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
27000 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
27010 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
27020 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
27030 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
27040 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27050 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
27060 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
27070 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
27080 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
27090 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
270a0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
270b0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
270c0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
270d0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
270e0 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
270f0 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
27100 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
27110 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
27120 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
27130 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
27140 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
27150 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
27160 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
27170 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
27180 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
27190 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
271a0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
271b0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
271c0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
271d0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
271e0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
271f0 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
27200 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
27210 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
27220 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
27230 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
27240 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
27250 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
27260 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
27270 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
27280 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
27290 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
272a0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
272b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
272c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
272d0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
272e0 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
272f0 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
27300 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
27310 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
27320 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
27330 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
27340 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
27350 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
27360 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
27370 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
27380 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
27390 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
273a0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
273b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
273c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
273d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
273e0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
273f0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
27400 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
27410 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c  ar *zParam);.SQL
27420 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
27430 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
27440 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
27450 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27460 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
27470 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
27480 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  lt);.SQLITE_API 
27490 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51  sqlite3_int64 SQ
274a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
274b0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
274c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
274d0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
274e0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
274f0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
27500 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
27510 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
27520 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
27530 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27540 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
27550 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
27560 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
27570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
27580 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
27590 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
275a0 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
275b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
275c0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
275d0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
275e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
275f0 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
27600 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
27610 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
27620 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
27630 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
27640 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
27650 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27660 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
27670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27680 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
27690 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
276a0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
276b0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
276c0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
276d0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
276e0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
276f0 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
27700 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
27710 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
27720 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27730 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
27740 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
27750 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
27760 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
27770 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27780 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
27790 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
277a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
277b0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
277c0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
277d0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
277e0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
277f0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
27800 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
27810 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
27820 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
27830 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
27840 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
27850 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
27860 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
27870 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
27880 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
27890 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
278a0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
278b0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
278c0 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
278d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
278e0 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
278f0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
27900 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27910 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
27920 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
27930 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27940 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27950 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
27960 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
27970 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
27980 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
27990 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
279a0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
279b0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
279c0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
279d0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
279e0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
279f0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
27a00 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
27a10 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
27a20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
27a30 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
27a40 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
27a50 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
27a60 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
27a70 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
27a80 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
27a90 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
27aa0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
27ab0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
27ac0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
27ad0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
27ae0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
27af0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
27b00 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
27b10 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
27b20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27b30 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
27b40 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27b50 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
27b60 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27b70 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
27b80 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
27b90 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
27ba0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
27bb0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
27bc0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
27bd0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
27be0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
27bf0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
27c00 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
27c10 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
27c20 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
27c30 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
27c40 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
27c50 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
27c60 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
27c70 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
27c80 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
27c90 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
27ca0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
27cb0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
27cc0 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
27cd0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
27ce0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
27cf0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
27d00 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
27d10 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
27d20 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65  ALL sqlite3_exte
27d30 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
27d40 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
27d50 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
27d60 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
27d70 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
27d80 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
27d90 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
27da0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
27db0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
27dc0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
27dd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
27de0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
27df0 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  LL sqlite3_errst
27e00 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
27e10 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
27e20 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
27e30 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
27e40 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
27e50 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
27e60 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
27e70 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
27e80 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
27e90 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
27ea0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
27eb0 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
27ec0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
27ed0 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
27ee0 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
27ef0 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
27f00 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
27f10 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
27f20 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
27f30 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
27f40 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
27f50 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
27f60 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
27f70 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
27f80 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
27f90 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
27fa0 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
27fb0 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
27fc0 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
27fd0 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
27fe0 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
27ff0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
28000 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
28010 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
28020 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
28030 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
28040 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
28050 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
28060 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
28070 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
28080 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
28090 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
280a0 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
280b0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
280c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
280d0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
280e0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
280f0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
28100 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
28110 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
28120 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
28130 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
28140 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
28150 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
28160 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
28170 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
28180 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
28190 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
281a0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
281b0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
281c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
281d0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
281e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
281f0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
28200 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
28210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28220 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
28230 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28240 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
28250 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
28260 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
28270 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
28280 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
28290 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
282a0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
282b0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
282c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
282d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
282e0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
282f0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
28300 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
28310 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
28320 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
28330 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
28340 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
28350 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
28360 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
28370 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
28380 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
28390 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
283a0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
283b0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
283c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
283d0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
283e0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
283f0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
28400 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
28410 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
28420 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
28430 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
28440 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
28450 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
28460 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
28470 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
28480 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
28490 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
284a0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
284b0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
284c0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
284d0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
284e0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
284f0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
28500 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
28510 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
28520 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
28530 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
28540 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
28550 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
28560 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
28570 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
28580 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
28590 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
285a0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
285b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
285c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
285d0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
285e0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
285f0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
28600 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
28610 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
28620 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
28630 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
28640 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
28650 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
28660 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28670 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
28680 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
28690 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
286a0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
286b0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
286c0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
286d0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
286e0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
286f0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
28700 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
28710 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
28720 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
28730 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
28740 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
28750 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
28760 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
28770 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
28780 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
28790 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
287a0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
287b0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
287c0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
287d0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
287e0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
287f0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
28800 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
28810 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
28820 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
28830 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
28840 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
28850 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
28860 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
28870 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
28880 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
28890 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
288a0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
288b0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
288c0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
288d0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
288e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
288f0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
28900 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
28910 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
28920 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
28930 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
28940 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
28950 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
28960 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
28970 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
28980 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
28990 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
289a0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
289b0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
289c0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
289d0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53  e releases..*/.S
289e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
289f0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
28a00 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
28a10 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
28a20 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
28a30 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
28a40 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
28a50 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
28a60 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
28a70 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
28a80 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
28a90 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
28aa0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
28ab0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
28ac0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
28ad0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
28ae0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
28af0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
28b00 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
28b10 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
28b20 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
28b30 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
28b40 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
28b50 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
28b60 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
28b70 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
28b80 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
28b90 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
28ba0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
28bb0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28bc0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
28bd0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28be0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
28bf0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
28c00 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
28c10 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
28c20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
28c30 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
28c40 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
28c50 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
28c60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28c70 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
28c80 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
28c90 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
28ca0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28cb0 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
28cc0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
28cd0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
28ce0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
28cf0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28d00 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
28d10 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
28d20 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
28d30 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
28d40 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28d50 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28d60 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
28d70 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
28d80 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
28d90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28da0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
28db0 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
28dc0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
28dd0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
28de0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28df0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
28e00 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
28e10 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
28e20 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
28e30 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
28e40 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
28e50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
28e60 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
28e70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28e80 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
28e90 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
28ea0 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
28eb0 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
28ec0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28ed0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
28ee0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
28ef0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
28f00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
28f10 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
28f20 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
28f30 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
28f40 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
28f50 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
28f60 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
28f70 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
28f80 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
28f90 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
28fa0 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
28fb0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
28fc0 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
28fd0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
28fe0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
28ff0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
29000 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29010 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
29020 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29030 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
29040 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
29050 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
29060 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29070 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
29080 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29090 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
290a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
290b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
290c0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
290d0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
290e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
290f0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29100 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
29110 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
29120 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
29130 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
29140 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29150 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
29160 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
29170 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
29180 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
29190 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
291a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
291b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
291c0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
291d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
291e0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
291f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29200 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
29210 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
29220 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
29230 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
29240 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
29250 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
29260 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29270 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
29280 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29290 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
292a0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
292b0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
292c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
292d0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
292e0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
292f0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29300 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
29310 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29320 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
29330 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
29340 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
29350 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29360 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
29370 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
29380 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
29390 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
293a0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
293b0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
293c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
293d0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
293e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
293f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29400 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
29410 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
29420 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
29430 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
29440 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
29450 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
29460 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
29470 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
29480 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29490 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
294a0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
294b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
294c0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
294d0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
294e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
294f0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
29500 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
29510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29520 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
29530 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
29540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29550 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
29560 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
29570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29580 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29590 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
295a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
295b0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
295c0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
295d0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
295e0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
295f0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
29600 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
29610 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
29620 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
29630 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52  qlite3.** CONSTR
29640 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
29650 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  tmt.**.** To exe
29660 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
29670 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
29680 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
29690 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
296a0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
296b0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
296c0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
296d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
296e0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
296f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29700 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
29710 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
29720 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
29730 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
29740 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
29750 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
29760 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
29770 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
29780 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
29790 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
297a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
297b0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
297c0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
297d0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
297e0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
297f0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
29800 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
29810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
29820 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
29830 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
29840 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
29850 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
29860 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
29870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29880 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
29890 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
298a0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
298b0 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  nt is negative, 
298c0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
298d0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
298e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
298f0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
29900 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
29910 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e  n it is the.** n
29920 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72  umber of bytes r
29930 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
29940 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72  ^If nByte is zer
29950 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61  o, then no prepa
29960 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
29970 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a   is generated..*
29980 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  * If the caller 
29990 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73  knows that the s
299a0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
299b0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
299c0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  , then.** there 
299d0 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f  is a small perfo
299e0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
299f0 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   to passing an n
29a00 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
29a10 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  hat.** is the nu
29a20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
29a30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
29a40 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
29a50 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
29a60 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
29a70 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
29a80 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
29a90 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
29aa0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
29ab0 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
29ac0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
29ad0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
29ae0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
29af0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
29b00 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
29b10 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
29b20 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
29b30 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
29b40 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
29b50 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
29b60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
29b70 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
29b80 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
29b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29ba0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
29bb0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
29bc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
29bd0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
29be0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
29bf0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
29c00 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
29c10 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
29c20 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
29c30 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
29c40 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
29c50 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
29c60 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
29c70 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
29c80 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
29c90 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
29ca0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
29cb0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
29cc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
29cd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
29ce0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
29cf0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
29d00 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
29d10 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
29d20 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
29d30 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
29d40 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
29d50 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
29d60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
29d70 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
29d80 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
29d90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
29da0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29db0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
29dc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29dd0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
29de0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
29df0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
29e00 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
29e10 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
29e20 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
29e30 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
29e40 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
29e50 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
29e60 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
29e70 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
29e80 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
29e90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29ea0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
29eb0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
29ec0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
29ed0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
29ee0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
29ef0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
29f00 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
29f10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29f20 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
29f30 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
29f40 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
29f50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
29f60 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
29f70 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
29f80 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
29f90 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
29fa0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
29fb0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
29fc0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
29fd0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
29fe0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
29ff0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
2a000 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
2a010 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
2a020 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
2a030 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
2a040 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
2a050 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
2a060 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
2a070 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
2a080 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
2a090 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
2a0a0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
2a0b0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
2a0c0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
2a0d0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
2a0e0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
2a0f0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
2a100 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
2a110 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
2a120 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
2a130 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
2a140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2a150 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
2a160 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
2a170 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2a180 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
2a190 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
2a1a0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
2a1b0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
2a1c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a1d0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
2a1e0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
2a1f0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
2a200 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
2a210 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
2a220 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
2a230 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
2a240 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
2a250 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
2a260 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
2a270 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
2a280 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2a290 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2a2a0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
2a2b0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
2a2c0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
2a2d0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2a2e0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2a2f0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
2a300 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
2a310 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
2a320 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
2a330 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2a340 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
2a350 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
2a360 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
2a370 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
2a380 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
2a390 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2a3a0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
2a3b0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
2a3c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a3d0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
2a3e0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
2a3f0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
2a400 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
2a410 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
2a420 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
2a430 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
2a440 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2a450 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
2a460 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
2a470 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
2a480 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
2a490 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
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 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
2a4c0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
2a4d0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
2a4e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
2a4f0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
2a500 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
2a510 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
2a520 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ol>.*/.SQLITE_A
2a530 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2a540 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72  DCALL sqlite3_pr
2a550 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
2a560 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a570 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a580 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a590 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2a5a0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a5b0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2a5c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a5e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a5f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a600 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a610 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a620 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a630 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a640 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2a650 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a660 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a670 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a680 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a690 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2a6a0 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2a6b0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2a6c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a6d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a6e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2a6f0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2a700 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a710 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2a720 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a740 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a750 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a760 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a770 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a780 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a790 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a7a0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2a7b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a7c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a7d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a7e0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a7f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2a800 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2a810 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
2a820 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a830 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2a840 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2a850 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2a860 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2a870 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2a880 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2a890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2a8a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2a8b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2a8c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2a8d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2a8e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2a8f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a900 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2a910 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2a920 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2a930 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2a940 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
2a950 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2a960 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
2a970 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
2a980 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2a990 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2a9a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a9b0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2a9c0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2a9d0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2a9e0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2a9f0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2aa00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2aa10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2aa20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2aa30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2aa40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2aa50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2aa60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2aa70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2aa80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2aa90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2aaa0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
2aab0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
2aac0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
2aad0 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
2aae0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2aaf0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2ab00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2ab10 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
2ab20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
2ab30 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
2ab40 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2ab50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ab60 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
2ab70 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
2ab80 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
2ab90 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2aba0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2abb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2abc0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  16_v2()]..*/.SQL
2abd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2abe0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
2abf0 4c 4c 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  LL sqlite3_sql(s
2ac00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2ac10 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2ac20 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2ac30 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2ac40 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2ac50 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2ac60 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ac70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ac80 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2ac90 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2aca0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2acb0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2acc0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2acd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ace0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2acf0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2ad00 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2ad10 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2ad20 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2ad30 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2ad40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2ad50 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2ad60 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2ad70 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2ad80 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2ad90 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2ada0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2adb0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2adc0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2add0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2ade0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2adf0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2ae00 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2ae10 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2ae20 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2ae30 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2ae40 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2ae50 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2ae60 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2ae70 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2ae80 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2ae90 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2aea0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2aeb0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2aec0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2aed0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2aee0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2aef0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2af00 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2af10 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2af20 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2af30 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2af40 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2af50 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2af60 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2af70 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2af80 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2af90 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2afa0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2afb0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2afc0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2afd0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2afe0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2aff0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2b000 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2b010 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2b020 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2b030 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2b040 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2b050 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2b060 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2b070 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2b080 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2b090 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2b0a0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2b0b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2b0c0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2b0d0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2b0e0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2b0f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2b100 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2b110 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2b120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2b130 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2b140 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2b150 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2b160 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b170 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51  s on disk..*/.SQ
2b180 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b190 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b1a0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2b1b0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
2b1c0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b1d0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2b1e0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
2b1f0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
2b200 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54  een Reset.** MET
2b210 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b220 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b230 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2b240 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b250 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2b260 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
2b270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b280 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
2b290 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
2b2a0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
2b2b0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b2c0 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
2b2d0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
2b2e0 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
2b2f0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2b300 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2b310 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2b320 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2b330 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2b340 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2b350 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2b360 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2b370 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2b380 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2b390 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2b3a0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2b3b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2b3c0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2b3d0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2b3e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2b3f0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2b400 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2b410 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2b420 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2b430 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2b440 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2b450 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2b460 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2b470 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2b480 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2b490 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2b4a0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2b4b0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2b4c0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2b4d0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2b4e0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2b4f0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2b500 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2b510 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2b520 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2b530 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  n open..*/.SQLIT
2b540 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b550 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b560 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
2b570 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2b580 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
2b590 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2b5a0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2b5b0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2b5c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b5d0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2b5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2b5f0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2b600 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2b610 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2b620 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2b630 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2b640 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2b650 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2b660 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2b670 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2b680 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2b690 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2b6a0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2b6b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
2b6c0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
2b6d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2b6e0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
2b6f0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
2b700 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
2b710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2b720 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
2b730 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
2b740 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
2b750 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
2b760 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
2b770 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2b780 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
2b790 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
2b7a0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
2b7b0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
2b7c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b7d0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
2b7e0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
2b7f0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
2b800 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
2b810 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
2b820 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
2b830 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
2b840 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2b850 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2b860 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69  3_value_dup()] i
2b870 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2b880 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63  used to construc
2b890 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74  t a new .** prot
2b8a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b8b0 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72  lue from an unpr
2b8c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b8d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
2b8e0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
2b8f0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
2b900 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
2b910 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
2b920 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
2b930 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
2b940 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
2b950 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
2b960 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b970 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
2b980 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
2b990 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2b9a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b9b0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
2b9c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
2b9d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
2b9e0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
2b9f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
2ba00 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
2ba10 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
2ba20 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
2ba30 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
2ba40 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
2ba50 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
2ba60 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
2ba70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2ba80 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
2ba90 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2baa0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
2bab0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
2bac0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
2bad0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
2bae0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2baf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
2bb00 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
2bb10 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
2bb20 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
2bb30 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
2bb40 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
2bb50 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2bb60 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
2bb70 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
2bb80 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
2bb90 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2bba0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2bbb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2bbc0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
2bbd0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
2bbe0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
2bbf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2bc00 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
2bc10 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
2bc20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
2bc30 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
2bc40 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
2bc50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2bc60 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
2bc70 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
2bc80 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2bc90 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2bca0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2bcb0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2bcc0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
2bcd0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
2bce0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2bcf0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
2bd00 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
2bd10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2bd20 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2bd30 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2bd40 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
2bd50 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
2bd60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2bd70 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
2bd80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
2bd90 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
2bda0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2bdb0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
2bdc0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
2bdd0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2bde0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2bdf0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2be00 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2be10 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2be20 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2be30 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2be40 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2be50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2be60 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2be70 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2be80 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2be90 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2bea0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2beb0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2bec0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2bed0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2bee0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bef0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2bf00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2bf10 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2bf20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2bf30 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2bf40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2bf50 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2bf60 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2bf70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2bf80 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2bf90 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2bfa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2bfb0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2bfc0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2bfd0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2bfe0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2bff0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2c000 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2c010 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2c020 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2c030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c040 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2c050 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2c060 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2c070 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2c080 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2c090 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2c0a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2c0b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2c0c0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2c0d0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2c0e0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2c0f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2c100 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2c110 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2c120 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2c130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2c140 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2c150 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2c160 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2c170 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2c180 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2c190 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2c1a0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2c1b0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2c1c0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2c1d0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2c1e0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2c1f0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2c200 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2c210 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2c220 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2c230 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2c240 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2c250 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2c260 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2c270 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2c280 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2c290 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2c2a0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2c2b0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2c2c0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2c2d0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2c2e0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2c2f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2c300 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2c310 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2c320 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2c330 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2c340 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2c350 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2c360 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2c370 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2c380 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2c390 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2c3a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c3b0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2c3c0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2c3d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2c3e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2c3f0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2c400 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2c410 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2c420 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2c430 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2c440 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2c450 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2c460 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2c470 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2c480 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2c490 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2c4a0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2c4b0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2c4c0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2c4d0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2c4e0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2c4f0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2c500 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2c510 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2c520 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2c530 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2c540 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2c550 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2c560 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2c570 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2c580 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2c590 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2c5a0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2c5b0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2c5c0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2c5d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2c5e0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2c5f0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2c600 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2c610 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2c620 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2c630 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2c640 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2c650 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2c660 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2c670 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c680 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2c690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c6a0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2c6b0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2c6c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2c6d0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2c6e0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2c6f0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2c700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2c710 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2c720 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2c730 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2c740 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2c750 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2c760 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2c770 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2c780 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2c790 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2c7a0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2c7b0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2c7c0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2c7d0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2c7e0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2c7f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2c800 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2c810 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2c820 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c830 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2c840 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2c850 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2c860 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2c870 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2c880 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2c890 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2c8a0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2c8b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c8c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2c8d0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2c8e0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2c8f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2c900 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2c910 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2c920 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2c930 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2c940 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2c950 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2c960 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2c970 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2c980 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2c990 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2c9a0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2c9b0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2c9c0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2c9d0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2c9e0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2c9f0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2ca00 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2ca10 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2ca20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2ca30 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2ca40 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2ca50 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2ca60 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2ca70 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2ca80 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2ca90 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2caa0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2cab0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2cac0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2cad0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2cae0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2caf0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2cb00 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2cb10 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2cb20 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2cb30 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2cb40 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2cb50 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2cb60 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2cb70 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2cb80 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2cb90 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2cba0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2cbb0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2cbc0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2cbd0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2cbe0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2cbf0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2cc00 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2cc10 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2cc20 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2cc30 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2cc40 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2cc50 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2cc60 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2cc70 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2cc80 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2cc90 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2cca0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2ccb0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2ccc0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2ccd0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2cce0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2ccf0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2cd00 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2cd10 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2cd20 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2cd30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2cd40 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2cd50 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2cd60 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2cd70 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2cd80 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2cd90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2cda0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2cdb0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2cdc0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2cdd0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2cde0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2cdf0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2ce00 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2ce10 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2ce20 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2ce30 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2ce40 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2ce50 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2ce60 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2ce70 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2ce80 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2ce90 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2cea0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2ceb0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2cec0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2ced0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2cee0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2cef0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2cf00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2cf10 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2cf20 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2cf30 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2cf40 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2cf50 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2cf60 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2cf70 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2cf80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2cf90 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2cfa0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2cfb0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2cfc0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2cfd0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2cfe0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2cff0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2d000 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2d010 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2d020 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2d030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2d040 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2d050 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2d060 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2d070 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2d080 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2d090 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2d0a0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2d0b0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2d0c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2d0d0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2d0e0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2d0f0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2d100 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2d110 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2d120 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2d130 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2d140 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2d150 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2d160 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2d170 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2d180 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2d190 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2d1a0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2d1b0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2d1c0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2d1d0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2d1e0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2d1f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2d200 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2d210 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2d220 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2d230 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2d240 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2d250 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2d260 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2d270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d280 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2d290 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2d2a0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2d2b0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2d2c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2d2d0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2d2e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2d2f0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2d300 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2d310 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2d320 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2d330 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2d340 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2d350 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2d360 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2d370 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2d380 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2d390 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2d3a0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2d3b0 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2d3c0 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2d3d0 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2d3e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2d3f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2d400 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2d410 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2d420 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2d430 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2d440 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2d450 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2d460 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d470 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2d480 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d490 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2d4a0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2d4b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2d4c0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2d4d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d4e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2d4f0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2d500 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d510 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2d520 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2d530 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d540 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d550 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2d560 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2d570 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2d580 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2d590 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2d5a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2d5b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2d5c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2d5d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d5e0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2d5f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d600 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
2d610 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d620 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d630 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2d640 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2d650 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2d660 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2d670 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  L sqlite3_bind_i
2d680 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2d690 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2d6a0 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
2d6b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2d6c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2d6d0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2d6e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  _stmt*, int);.SQ
2d6f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2d700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d710 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2d720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2d730 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2d740 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d750 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d760 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d770 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d780 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d790 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2d7a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2d7b0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2d7c0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2d7d0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d7e0 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2d7f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2d800 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2d810 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2d820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d830 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2d840 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2d850 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53  har encoding);.S
2d860 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d870 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d880 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2d890 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d8a0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2d8b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2d8c0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d8d0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d8e0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2d8f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d900 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54  t, int n);.SQLIT
2d910 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d920 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d930 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34  _bind_zeroblob64
2d940 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d950 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  int, sqlite3_uin
2d960 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2d970 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2d980 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
2d990 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d9a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2d9b0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2d9c0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
2d9d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
2d9e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
2d9f0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
2da00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
2da10 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
2da20 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
2da30 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
2da40 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
2da50 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
2da60 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
2da70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2da80 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
2da90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2daa0 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
2dab0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
2dac0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
2dad0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2dae0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
2daf0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
2db00 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
2db10 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
2db20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
2db30 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
2db40 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
2db50 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
2db60 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
2db70 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
2db80 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
2db90 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
2dba0 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
2dbb0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
2dbc0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
2dbd0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2dbe0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2dbf0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2dc00 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2dc10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2dc20 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
2dc30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2dc40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2dc50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2dc60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2dc70 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  L sqlite3_bind_p
2dc80 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2dc90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2dca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dcb0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2dcc0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
2dcd0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2dce0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dcf0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2dd00 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2dd10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2dd20 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2dd30 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2dd40 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2dd50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dd60 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2dd70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2dd80 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2dd90 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2dda0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2ddb0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2ddc0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2ddd0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2dde0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2ddf0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2de00 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2de10 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2de20 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2de30 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2de40 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2de50 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2de60 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2de70 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2de80 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2de90 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2dea0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2deb0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2dec0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2ded0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2dee0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2def0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2df00 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2df10 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2df20 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2df30 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2df40 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2df50 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2df60 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2df70 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2df80 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2df90 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2dfa0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2dfb0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2dfc0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2dfd0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2dfe0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2dff0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2e000 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2e010 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2e020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e030 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2e040 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e050 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2e060 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2e070 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e080 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2e090 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2e0a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2e0b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2e0c0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2e0d0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2e0e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2e0f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2e100 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e110 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2e120 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2e130 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2e140 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2e150 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e160 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2e170 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
2e180 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
2e190 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
2e1a0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
2e1b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2e1c0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
2e1d0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
2e1e0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
2e1f0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
2e200 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2e210 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
2e220 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
2e230 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
2e240 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
2e250 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
2e260 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
2e270 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
2e280 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
2e290 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
2e2a0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
2e2b0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
2e2c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
2e2d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2e2e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2e2f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e300 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2e310 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2e320 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2e330 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2e340 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e350 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e360 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e370 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2e380 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2e390 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2e3a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2e3b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2e3c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e3d0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2e3e0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2e3f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2e400 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e410 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
2e420 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2e430 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2e440 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e450 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2e460 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2e470 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2e480 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2e490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e4a0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2e4b0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2e4c0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2e4d0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2e4e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2e4f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2e500 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2e510 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2e520 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e530 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2e540 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2e550 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2e560 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e570 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2e580 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2e590 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2e5a0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2e5b0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2e5c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2e5d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2e5e0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2e5f0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2e600 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2e610 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2e620 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2e630 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2e640 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2e650 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2e660 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2e670 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2e680 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2e690 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2e6a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2e6b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e6c0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2e6d0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2e6e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e6f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2e700 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2e710 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2e720 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2e730 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2e740 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2e750 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2e760 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2e770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2e780 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2e790 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2e7a0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2e7b0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2e7c0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2e7d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2e7e0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2e7f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2e800 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2e810 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2e820 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2e830 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2e840 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e850 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2e860 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2e870 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2e880 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e890 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2e8a0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2e8b0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2e8c0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2e8d0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2e8e0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2e8f0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2e900 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2e910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2e920 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2e930 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2e940 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2e950 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2e960 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2e970 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2e980 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2e990 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2e9a0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2e9b0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2e9c0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2e9d0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2e9e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2e9f0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2ea00 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2ea10 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2ea20 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2ea30 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2ea40 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2ea50 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2ea60 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2ea70 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2ea80 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2ea90 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2eaa0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2eab0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2eac0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ead0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2eae0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2eaf0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2eb00 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2eb10 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2eb20 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2eb30 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2eb40 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2eb50 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2eb60 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2eb70 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2eb80 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2eb90 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2eba0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2ebb0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54  e next..*/.SQLIT
2ebc0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2ebd0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2ebe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ebf0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2ec00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
2ec10 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2ec20 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2ec30 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2ec40 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2ec50 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2ec60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ec70 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2ec80 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2ec90 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2eca0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ecb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2ecc0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2ecd0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2ece0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2ecf0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2ed00 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2ed10 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2ed20 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2ed30 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2ed40 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2ed50 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2ed60 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2ed70 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2ed80 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2ed90 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2eda0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2edb0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2edc0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2edd0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2ede0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2edf0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2ee00 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2ee10 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2ee20 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2ee30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ee40 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2ee50 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2ee60 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2ee70 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2ee80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2ee90 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2eea0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2eeb0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2eec0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2eed0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2eee0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2eef0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2ef00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ef10 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2ef20 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2ef30 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2ef40 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2ef50 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2ef60 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2ef70 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2ef80 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2ef90 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2efa0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2efb0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2efc0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2efd0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2efe0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2eff0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2f000 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2f010 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f020 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2f030 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2f040 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2f050 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2f060 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2f070 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2f080 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2f090 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2f0a0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2f0b0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2f0c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2f0d0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2f0e0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2f0f0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2f100 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2f110 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2f120 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2f130 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2f140 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2f150 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2f160 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2f170 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2f180 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2f190 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2f1a0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2f1b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2f1c0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2f1d0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2f1e0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2f1f0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2f200 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2f210 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2f220 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2f230 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2f240 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2f250 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2f260 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2f270 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2f280 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2f290 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2f2a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2f2b0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2f2c0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2f2d0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2f2e0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2f2f0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2f300 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2f310 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2f320 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2f330 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2f340 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2f350 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2f360 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2f370 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2f380 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2f390 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2f3a0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2f3b0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2f3c0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2f3d0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2f3e0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2f3f0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2f400 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2f410 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2f420 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2f430 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2f440 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2f450 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2f460 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2f470 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2f480 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2f490 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2f4a0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2f4b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2f4c0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2f4d0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2f4e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f4f0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2f500 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2f510 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2f520 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2f530 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2f540 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2f550 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2f560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2f570 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2f580 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2f590 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f5a0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2f5b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2f5c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2f5d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f5e0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2f5f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2f600 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f610 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2f620 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f630 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2f640 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2f650 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2f660 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f670 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2f680 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2f690 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f6a0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2f6b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2f6c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2f6d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f6e0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2f6f0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2f700 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2f710 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2f720 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f730 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
2f740 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2f750 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2f760 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2f770 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2f780 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2f790 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2f7a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2f7b0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2f7c0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2f7d0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2f7e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2f7f0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2f800 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2f810 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2f820 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2f830 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2f840 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2f850 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2f860 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2f870 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2f880 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2f890 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2f8a0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2f8b0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2f8c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2f8d0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2f8e0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2f8f0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2f900 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2f910 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2f920 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2f930 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2f940 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2f950 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2f960 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2f970 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2f980 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2f990 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2f9a0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2f9b0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2f9c0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2f9d0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2f9e0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2f9f0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2fa00 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2fa10 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2fa20 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2fa30 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2fa40 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2fa50 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2fa60 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2fa70 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2fa80 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2fa90 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2faa0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2fab0 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2fac0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2fad0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2fae0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2faf0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2fb00 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2fb10 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2fb20 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2fb30 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2fb40 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2fb50 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2fb60 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2fb70 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2fb80 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53  ose values..*/.S
2fb90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2fba0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2fbb0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2fbc0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2fbd0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2fbe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fbf0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
2fc00 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2fc10 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2fc20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fc30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2fc40 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2fc50 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2fc60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2fc70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
2fc80 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2fc90 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2fca0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2fcb0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2fcc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2fcd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2fce0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2fcf0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2fd00 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2fd10 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2fd20 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2fd30 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2fd40 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2fd50 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2fd60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2fd70 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2fd80 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2fd90 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2fda0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2fdb0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2fdc0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2fdd0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2fde0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2fdf0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2fe00 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2fe10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2fe20 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2fe30 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2fe40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2fe50 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2fe60 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2fe70 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2fe80 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2fe90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2fea0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2feb0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2fec0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2fed0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2fee0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2fef0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2ff00 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2ff10 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2ff20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2ff30 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2ff40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2ff50 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2ff60 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2ff70 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2ff80 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2ff90 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2ffa0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2ffb0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2ffc0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2ffd0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2ffe0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2fff0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
30000 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
30010 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
30020 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
30030 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
30040 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
30050 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
30060 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
30070 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
30080 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
30090 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
300a0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
300b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
300c0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
300d0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
300e0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
300f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
30100 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
30110 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
30120 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
30130 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
30140 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
30150 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
30160 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
30170 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
30180 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
30190 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
301a0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
301b0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
301c0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
301d0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
301e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
301f0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
30200 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
30210 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
30220 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
30230 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
30240 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
30250 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
30260 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
30270 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
30280 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
30290 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
302a0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
302b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
302c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
302d0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
302e0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
302f0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
30300 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
30310 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
30320 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
30330 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
30340 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
30350 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
30360 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
30370 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
30380 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
30390 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
303a0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
303b0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
303c0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
303d0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
303e0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
303f0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
30400 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
30410 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
30420 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
30430 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
30440 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
30450 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
30460 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
30470 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
30480 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
30490 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
304a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
304b0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
304c0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
304d0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
304e0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
304f0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
30500 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
30510 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
30520 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
30530 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
30540 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
30550 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
30560 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
30570 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
30580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30590 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
305a0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
305b0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
305c0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
305d0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
305e0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
305f0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
30600 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
30610 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
30620 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
30630 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
30640 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
30650 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
30660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30670 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
30680 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
30690 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
306a0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
306b0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
306c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
306d0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
306e0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
306f0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
30700 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
30710 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
30720 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
30730 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
30740 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
30750 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
30760 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
30770 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
30780 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
30790 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
307a0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
307b0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
307c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
307d0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
307e0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
307f0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
30800 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
30810 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
30820 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
30830 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
30840 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
30850 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
30860 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
30870 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
30880 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
30890 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
308a0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
308b0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
308c0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
308d0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
308e0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
308f0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
30900 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
30910 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
30920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
30930 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
30940 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
30950 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
30960 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
30970 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30980 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
30990 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
309a0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
309b0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
309c0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
309d0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
309e0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
309f0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
30a00 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
30a10 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
30a20 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
30a30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
30a40 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
30a50 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
30a60 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
30a70 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
30a80 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
30a90 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
30aa0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
30ab0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
30ac0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
30ad0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
30ae0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
30af0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
30b00 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
30b10 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
30b20 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
30b30 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30b40 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
30b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30b60 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
30b70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
30b80 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
30b90 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
30ba0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
30bb0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
30bc0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
30bd0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
30be0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
30bf0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
30c00 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
30c10 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
30c20 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
30c30 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
30c40 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
30c50 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
30c60 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
30c70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30c80 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
30c90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30ca0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
30cb0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
30cc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
30cd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
30ce0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
30cf0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
30d00 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
30d10 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
30d20 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
30d30 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
30d40 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
30d50 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
30d60 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
30d70 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
30d80 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
30d90 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
30da0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
30db0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
30dc0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
30dd0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
30de0 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
30df0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30e00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
30e10 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
30e20 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
30e30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
30e40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
30e50 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
30e60 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
30e70 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
30e80 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
30e90 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
30ea0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
30eb0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
30ec0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
30ed0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
30ee0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
30ef0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
30f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
30f10 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
30f20 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
30f30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
30f40 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
30f50 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
30f60 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
30f70 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
30f80 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
30f90 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The 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 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
30fc0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
30fd0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
30fe0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
30ff0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
31000 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
31010 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31020 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
31030 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
31040 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31050 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
31060 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
31070 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
31080 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
31090 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
310a0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
310b0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
310c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
310d0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
310e0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
310f0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
31100 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
31110 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
31120 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31140 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
31150 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31160 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61  DCALL sqlite3_da
31170 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
31180 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
311a0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
311b0 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
311c0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
311d0 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
311e0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
311f0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
31200 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
31210 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
31220 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
31230 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
31240 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
31250 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31260 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
31270 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
31280 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
31290 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
312a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
312b0 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
312c0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
312d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
312e0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
312f0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
31300 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
31310 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
31320 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
31330 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
31340 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
31350 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
31360 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
31370 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
31380 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
31390 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
313a0 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
313b0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
313c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
313d0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
313e0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
313f0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
31400 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
31410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
31420 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
31430 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
31440 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
31450 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
31460 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
31470 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
31480 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
31490 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
314a0 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
314b0 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
314c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
314d0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
314e0 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
314f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31500 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
31510 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
31520 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
31530 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
31540 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
31550 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
31560 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
31570 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
31580 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
31590 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
315a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
315b0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
315c0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
315d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
315e0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
315f0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
31600 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
31610 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
31620 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
31630 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
31640 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
31650 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
31660 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
31670 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
31680 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
31690 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
316a0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
316b0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
316c0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
316d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
316e0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
316f0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
31700 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
31710 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31720 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
31730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
31740 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
31750 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
31760 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
31770 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
31780 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
31790 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
317a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
317b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
317c0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
317d0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
317e0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
317f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31800 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
31810 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
31820 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
31830 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
31840 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31850 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
31860 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
31870 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
31880 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31890 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
318a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
318b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
318c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
318d0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
318e0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
318f0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
31900 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
31910 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
31920 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
31930 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
31940 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
31950 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31960 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
31970 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
31980 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
31990 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
319a0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
319b0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
319c0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
319d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
319e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
319f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
31a00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
31a10 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
31a20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
31a30 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
31a40 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
31a50 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
31a60 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
31a70 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
31a80 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
31a90 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
31aa0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
31ab0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
31ac0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
31ad0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
31ae0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
31af0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
31b00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
31b10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
31b20 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
31b30 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
31b40 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
31b50 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
31b60 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
31b70 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
31b80 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
31b90 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
31ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31bb0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
31bc0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
31bd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
31be0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
31bf0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
31c00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
31c10 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
31c20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
31c30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
31c40 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
31c50 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
31c60 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
31c70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
31c80 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
31c90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
31ca0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
31cb0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
31cc0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31cd0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
31ce0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
31cf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31d00 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
31d10 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
31d20 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
31d30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31d40 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
31d50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
31d60 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
31d70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31d80 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
31d90 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
31da0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
31db0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
31dc0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
31dd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
31de0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
31df0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
31e00 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31e10 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
31e20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31e30 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
31e40 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
31e50 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
31e60 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
31e70 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
31e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31e90 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
31ea0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
31eb0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
31ec0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
31ed0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
31ee0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
31ef0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
31f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31f10 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
31f20 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
31f30 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
31f40 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
31f50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
31f60 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
31f70 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
31f80 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
31f90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31fa0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
31fb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
31fc0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
31fd0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
31fe0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
31ff0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
32000 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32010 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
32020 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32030 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
32040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32050 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
32060 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
32070 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
32080 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32090 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
320a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
320b0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
320c0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
320d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
320e0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
320f0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
32100 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
32110 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
32120 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
32130 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
32140 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
32150 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
32160 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
32170 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
32180 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
32190 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
321a0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
321b0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
321c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
321d0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
321e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
321f0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
32200 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
32210 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
32220 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
32230 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
32240 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
32250 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
32260 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
32270 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
32280 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
32290 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
322a0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
322b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
322c0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
322d0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
322e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
322f0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
32300 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
32310 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
32320 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32330 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
32340 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
32350 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
32360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
32370 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
32380 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32390 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
323a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
323b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
323c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
323d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
323e0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
323f0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
32400 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
32410 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
32420 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
32430 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
32440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32450 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
32460 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32470 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
32480 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
32490 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
324a0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
324b0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
324c0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
324d0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
324e0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
324f0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
32500 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
32510 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
32520 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
32530 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
32540 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
32550 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
32560 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
32570 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
32580 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
32590 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
325a0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
325b0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
325c0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
325d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
325e0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
325f0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
32600 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
32610 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
32620 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
32630 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
32640 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
32650 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
32660 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
32670 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
32680 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
32690 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
326a0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
326b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
326c0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
326d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
326e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
326f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
32700 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
32710 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
32720 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32730 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
32740 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
32750 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
32760 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
32770 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
32780 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
32790 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
327a0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
327b0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
327c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
327d0 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
327e0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
327f0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
32800 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
32810 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
32820 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32830 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
32840 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
32850 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
32860 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
32870 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
32880 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
32890 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
328a0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
328b0 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
328c0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
328d0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
328e0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
328f0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
32900 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
32910 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
32920 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
32930 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
32940 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
32950 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
32960 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
32970 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
32980 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
32990 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
329a0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
329b0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
329c0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
329d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
329e0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
329f0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
32a00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
32a10 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
32a20 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
32a30 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
32a40 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
32a50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
32a60 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
32a70 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
32a80 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
32a90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32aa0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
32ab0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
32ac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
32ad0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
32ae0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
32af0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
32b00 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
32b10 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
32b20 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
32b30 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
32b40 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
32b50 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
32b60 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
32b70 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
32b80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32b90 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
32ba0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
32bb0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
32bc0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
32bd0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
32be0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
32bf0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
32c00 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
32c10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32c20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
32c30 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
32c40 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
32c50 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
32c60 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
32c70 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
32c80 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
32c90 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
32ca0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
32cb0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
32cc0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
32cd0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
32ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32cf0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
32d00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32d10 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
32d20 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
32d30 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
32d40 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
32d50 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
32d60 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
32d70 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
32d80 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
32d90 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
32da0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
32db0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
32dc0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
32dd0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
32de0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
32df0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
32e00 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
32e10 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
32e20 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
32e30 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
32e40 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
32e50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
32e60 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
32e70 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
32e80 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
32e90 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
32ea0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
32eb0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
32ec0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
32ed0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
32ee0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
32ef0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
32f00 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
32f10 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
32f20 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
32f30 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
32f40 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
32f50 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
32f60 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
32f70 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
32f80 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
32f90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
32fa0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
32fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32fc0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
32fd0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
32fe0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
32ff0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33000 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
33010 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
33020 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
33030 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
33040 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
33050 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
33060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
33070 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
33080 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
33090 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
330a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
330b0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
330c0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
330d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
330e0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
330f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33100 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
33110 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
33120 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
33130 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
33140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33150 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
33160 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
33170 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
33180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33190 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
331a0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
331b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
331c0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
331d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
331e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
331f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
33200 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
33210 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
33220 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
33230 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
33240 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
33250 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
33260 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
33270 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
33280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
33290 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
332a0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
332b0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
332c0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
332d0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
332e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
332f0 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
33300 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
33310 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
33320 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
33330 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
33340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33350 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
33360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
33370 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
33380 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
33390 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
333a0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
333b0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
333c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
333d0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
333e0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
333f0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
33400 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
33410 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
33420 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
33430 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
33440 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
33450 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
33460 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
33470 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
33480 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
33490 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
334a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
334b0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
334c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
334d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
334e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
334f0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
33500 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33510 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
33520 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
33530 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33540 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33550 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33560 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33570 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
33580 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33590 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
335a0 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
335b0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
335c0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
335d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
335e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
335f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33610 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
33620 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33630 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
33640 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
33650 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
33660 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
33670 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33680 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33690 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
336a0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
336b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
336c0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
336d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
336e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
336f0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
33700 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33710 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
33720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33730 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33740 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
33750 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
33760 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
33770 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33780 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
33790 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51  qlite3_value *SQ
337a0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
337b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
337c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
337d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
337e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
337f0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
33800 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
33810 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
33820 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33830 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33840 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
33850 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
33860 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
33870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
33880 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33890 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
338a0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
338b0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
338c0 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
338d0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
338e0 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
338f0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
33900 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33910 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
33920 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
33930 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
33940 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
33950 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
33960 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
33970 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
33980 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
33990 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
339a0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
339b0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
339c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
339d0 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
339e0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
339f0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
33a00 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
33a10 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
33a20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33a30 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
33a40 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
33a50 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
33a60 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
33a70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
33a80 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
33a90 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
33aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
33ab0 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
33ac0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
33ad0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
33ae0 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
33af0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
33b00 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
33b10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
33b20 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
33b30 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
33b40 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
33b50 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
33b60 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
33b70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33b80 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
33b90 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
33ba0 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
33bb0 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
33bc0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
33bd0 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
33be0 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
33bf0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
33c00 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
33c10 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
33c20 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
33c30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
33c40 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
33c50 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
33c60 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
33c70 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
33c80 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
33c90 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
33ca0 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
33cb0 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
33cc0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
33cd0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e  CALL sqlite3_fin
33ce0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
33cf0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
33d00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
33d10 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
33d20 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
33d30 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
33d40 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
33d50 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
33d60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
33d70 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
33d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33d90 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
33da0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
33db0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
33dc0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
33dd0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
33de0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
33df0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
33e00 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
33e10 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
33e20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
33e30 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
33e40 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
33e50 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
33e60 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
33e70 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
33e80 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
33e90 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
33ea0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33eb0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
33ec0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
33ed0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
33ee0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
33ef0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
33f00 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
33f10 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
33f20 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
33f30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
33f40 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
33f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
33f60 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
33f70 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
33f80 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
33f90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
33fa0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
33fb0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
33fc0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
33fd0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33fe0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
33ff0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
34000 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34010 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34020 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
34030 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
34040 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
34050 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
34060 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
34070 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34080 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
34090 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
340a0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
340b0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
340c0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
340d0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
340e0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
340f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
34100 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
34110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34120 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54  ent] S..*/.SQLIT
34130 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
34140 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34150 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
34160 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
34170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
34180 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
34190 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
341a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
341b0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
341c0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
341d0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
341e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
341f0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
34200 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
34210 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
34220 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
34230 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
34240 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
34250 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
34260 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
34270 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
34280 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
34290 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
342a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
342b0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
342c0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
342d0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
342e0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
342f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
34300 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
34310 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
34320 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34330 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
34340 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
34350 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
34360 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
34370 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
34380 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
34390 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
343a0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
343b0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
343c0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
343d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
343e0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
343f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34400 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
34410 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34420 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
34430 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
34440 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
34450 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
34460 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
34470 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
34480 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
34490 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
344a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
344b0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
344c0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
344d0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
344e0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
344f0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
34500 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
34510 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
34520 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34530 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
34540 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
34550 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
34560 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
34570 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
34580 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
34590 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
345a0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
345b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
345c0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
345d0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
345e0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
345f0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
34600 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
34610 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
34620 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
34630 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
34640 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
34650 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
34660 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
34670 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
34680 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34690 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
346a0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
346b0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
346c0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
346d0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
346e0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
346f0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
34700 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
34710 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34720 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
34730 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
34740 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
34750 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
34760 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
34770 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
34780 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
34790 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
347a0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
347b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
347c0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
347d0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
347e0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
347f0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
34800 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34810 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
34820 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
34830 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
34840 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
34850 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
34860 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
34870 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
34880 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
34890 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
348a0 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
348b0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
348c0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
348d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
348e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
348f0 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
34900 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
34910 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
34920 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
34930 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
34940 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
34950 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
34960 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
34970 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
34980 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
34990 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
349a0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
349b0 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
349c0 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
349d0 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
349e0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
349f0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
34a00 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
34a10 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
34a20 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
34a30 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
34a40 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
34a50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
34a60 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
34a70 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
34a80 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
34a90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
34aa0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
34ab0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
34ac0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
34ad0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
34ae0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
34af0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
34b00 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
34b10 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
34b20 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
34b30 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
34b40 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
34b50 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
34b60 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
34b70 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
34b80 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
34b90 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
34ba0 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
34bb0 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
34bc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
34bd0 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
34be0 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
34bf0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
34c00 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
34c10 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
34c20 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
34c30 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
34c40 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
34c50 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
34c60 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
34c70 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
34c80 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
34c90 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
34ca0 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
34cb0 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
34cc0 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
34cd0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
34ce0 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
34cf0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
34d00 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
34d10 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
34d20 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
34d30 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
34d40 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
34d50 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
34d60 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
34d70 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
34d80 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
34d90 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
34da0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
34db0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
34dc0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
34dd0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
34de0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
34df0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
34e00 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
34e10 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
34e20 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
34e30 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
34e40 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
34e50 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
34e60 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
34e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
34e80 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
34e90 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
34ea0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
34eb0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
34ec0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
34ed0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
34ee0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
34ef0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34f00 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
34f10 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
34f20 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
34f30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
34f40 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
34f50 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
34f60 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
34f70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
34f80 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
34f90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
34fa0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
34fb0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
34fc0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
34fd0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
34fe0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
34ff0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35000 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
35010 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
35020 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
35030 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35040 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
35050 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
35060 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
35070 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
35080 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
35090 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
350a0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
350b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
350c0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
350d0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
350e0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
350f0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
35100 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35110 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35120 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
35130 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35140 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
35150 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
35160 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
35170 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
35180 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
35190 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
351a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
351b0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
351c0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
351d0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
351e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
351f0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
35200 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
35210 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
35220 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
35230 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35240 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
35250 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
35260 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
35270 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
35280 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
35290 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
352a0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
352b0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
352c0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
352d0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
352e0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
352f0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
35300 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
35310 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
35320 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
35330 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
35340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
35350 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
35360 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
35370 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
35380 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
35390 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
353a0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
353b0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
353c0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
353d0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
353e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
353f0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
35400 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
35410 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
35420 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
35430 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
35440 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
35450 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
35460 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
35470 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
35480 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
35490 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
354a0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
354b0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
354c0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
354d0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
354e0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
354f0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
35500 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
35510 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
35520 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
35530 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
35540 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35550 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
35560 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35570 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
35580 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
35590 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
355a0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
355b0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
355c0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
355d0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
355e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
355f0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
35600 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
35610 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
35620 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
35630 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35640 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35650 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
35660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35670 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
35680 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
35690 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
356a0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
356b0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
356c0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
356d0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
356e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
356f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35700 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
35710 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
35720 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35730 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35740 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
35750 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
35760 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
35770 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
35780 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35790 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
357a0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
357b0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
357c0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
357d0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
357e0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
357f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
35800 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35810 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
35820 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
35830 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
35840 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35850 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35860 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
35870 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35880 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
35890 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
358a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
358b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
358c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
358d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
358e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
358f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
35900 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
35910 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
35920 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
35930 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35940 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35950 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
35960 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35970 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35980 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
35990 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
359a0 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
359b0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
359c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
359d0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
359e0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
359f0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
35a00 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
35a10 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
35a20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
35a30 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
35a40 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
35a50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35a60 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
35a70 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
35a80 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
35a90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
35aa0 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
35ab0 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
35ac0 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
35ad0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
35ae0 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
35af0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
35b00 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
35b10 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
35b20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
35b30 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
35b40 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
35b50 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
35b60 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
35b70 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
35b80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
35b90 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
35ba0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35bb0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
35bc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35bd0 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
35be0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
35bf0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
35c00 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
35c10 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
35c20 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
35c30 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
35c40 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
35c50 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
35c60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35c70 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
35c80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35c90 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
35ca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35cb0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
35cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35cd0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
35ce0 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
35cf0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
35d00 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
35d10 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
35d20 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
35d30 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
35d40 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
35d50 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
35d60 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
35d70 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
35d80 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
35d90 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
35da0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
35db0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
35dc0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
35dd0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
35de0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
35df0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65  functions.  To e
35e00 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d  ncourage program
35e10 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  mers to avoid.**
35e20 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
35e30 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78  , we will not ex
35e40 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20  plain what they 
35e50 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
35e60 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
35e70 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
35e80 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
35e90 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  ED int SQLITE_ST
35ea0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67  DCALL sqlite3_ag
35eb0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
35ec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
35ed0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
35ee0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
35ef0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
35f00 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
35f10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
35f20 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
35f30 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
35f40 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
35f50 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
35f60 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
35f70 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
35f80 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
35f90 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35fa0 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
35fb0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35fc0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
35fd0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
35fe0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
35ff0 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49 54 45  ATED void SQLITE
36000 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36010 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
36020 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
36030 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36040 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
36050 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
36060 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
36070 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
36080 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
36090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
360a0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
360b0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
360c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
360d0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
360e0 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
360f0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
36100 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
36110 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
36120 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
36130 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
36140 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
36150 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
36160 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
36170 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
36180 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
36190 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
361a0 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a  aggregate.  .**.
361b0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
361c0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
361d0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
361e0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
361f0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
36200 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36210 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
36220 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36230 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
36240 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
36250 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
36260 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36270 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
36280 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
36290 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
362a0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
362b0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
362c0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
362d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
362e0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
362f0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
36300 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36310 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
36320 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
36330 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
36340 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
36350 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
36360 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
36370 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36380 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
36390 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
363a0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
363b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
363c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
363d0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
363e0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
363f0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
36400 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36410 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
36420 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
36430 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
36440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
36450 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
36460 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
36470 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
36480 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
36490 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
364a0 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
364b0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
364c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
364d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
364e0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
364f0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
36500 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
36510 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
36520 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
36530 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36540 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
36550 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
36560 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
36570 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
36580 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
36590 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
365a0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
365b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
365c0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
365d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
365e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
365f0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
36600 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
36610 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
36620 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
36630 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
36640 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36650 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
36660 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
36670 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
36680 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
36690 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
366a0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
366b0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
366c0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
366d0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
366e0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
366f0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
36700 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
36710 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
36720 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
36730 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
36740 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
36750 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
36760 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
36770 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
36780 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
36790 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
367a0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
367b0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
367c0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
367d0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
367e0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
367f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
36800 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
36810 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
36820 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
36830 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
36840 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
36850 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
36860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
36870 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
36880 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
36890 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
368a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
368b0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
368c0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
368d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
368e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
368f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
36900 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
36910 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
36920 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
36930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
36940 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
36950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
36960 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
36970 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36980 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
36990 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
369a0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
369b0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
369c0 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
369d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
369e0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
369f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
36a00 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
36a10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
36a20 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
36a30 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
36a40 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
36a50 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36a60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
36a70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36a80 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
36a90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36aa0 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51  TE_API double SQ
36ab0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36ac0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
36ad0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
36ae0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
36af0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36b00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
36b10 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
36b20 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
36b30 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
36b40 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36b50 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
36b60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36b70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
36b80 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
36b90 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
36ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36bb0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
36bc0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
36bd0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
36be0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36bf0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
36c00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36c10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
36c20 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
36c30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36c40 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
36c50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36c60 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
36c70 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
36c80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36c90 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
36ca0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
36cb0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
36cc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36cd0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
36ce0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
36cf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
36d00 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
36d10 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
36d20 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
36d30 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
36d40 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
36d50 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
36d60 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
36d70 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
36d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
36d90 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
36da0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
36db0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
36dc0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
36dd0 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
36de0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36df0 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
36e00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
36e10 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
36e20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36e30 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36e40 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
36e50 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
36e60 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36e70 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
36e80 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
36e90 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
36ea0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
36eb0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
36ec0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36ed0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
36ee0 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
36ef0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
36f00 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
36f10 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
36f20 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36f30 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
36f40 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
36f50 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
36f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
36f70 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
36f80 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
36f90 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
36fa0 58 50 45 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69  XPERIMENTAL sqli
36fb0 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54  te3_value *SQLIT
36fc0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36fd0 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73  3_value_dup(cons
36fe0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
36ff0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
37000 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
37010 4c 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  L void SQLITE_ST
37020 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
37030 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
37040 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
37050 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
37060 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
37070 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
37080 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
37090 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
370a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
370b0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
370c0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
370d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
370e0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
370f0 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
37100 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
37110 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
37120 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
37130 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37140 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
37150 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
37160 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
37170 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
37180 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
37190 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
371a0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
371b0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
371c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
371d0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
371e0 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
371f0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37200 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
37210 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37220 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
37230 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37240 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
37250 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
37260 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
37270 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37280 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
37290 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
372a0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
372b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
372c0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
372d0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
372e0 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
372f0 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
37300 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
37310 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
37320 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
37330 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
37340 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
37350 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
37360 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
37370 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
37380 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
37390 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
373a0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
373b0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
373c0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
373d0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
373e0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
373f0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
37400 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
37410 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
37420 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37430 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37440 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
37450 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
37460 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
37470 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
37480 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
37490 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
374a0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
374b0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
374c0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
374d0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
374e0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
374f0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
37500 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37510 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
37520 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
37530 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
37540 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
37550 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
37560 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
37570 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
37580 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
37590 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
375a0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
375b0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
375c0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
375d0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
375e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
375f0 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
37600 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
37610 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
37620 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
37630 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
37640 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37650 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
37660 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
37670 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
37680 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
37690 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
376a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
376b0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
376c0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
376d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
376e0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
376f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
37700 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
37710 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
37720 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
37730 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
37740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
37750 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
37760 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
37770 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
37780 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
37790 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
377a0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
377b0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
377c0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
377d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
377e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
377f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
37800 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
37810 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
37820 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
37830 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
37840 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
37850 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
37860 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
37870 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37880 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
37890 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
378a0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
378b0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
378c0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
378d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
378e0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
378f0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
37900 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
37910 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
37920 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
37930 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
37940 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
37950 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
37960 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
37970 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37980 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
37990 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
379a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
379b0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
379c0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
379d0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
379e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
379f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
37a00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
37a10 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
37a20 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
37a30 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
37a40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37a50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
37a60 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
37a70 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
37a80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
37a90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
37aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37ac0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
37ad0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
37ae0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
37af0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
37b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37b10 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
37b20 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
37b30 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
37b40 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
37b50 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
37b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37b70 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
37b80 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
37b90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37ba0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
37bb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37bc0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
37bd0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
37be0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
37bf0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
37c00 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
37c10 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  nction..*/.SQLIT
37c20 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53  E_API sqlite3 *S
37c30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
37c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
37c50 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
37c60 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
37c70 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
37c80 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
37c90 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
37ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
37cb0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
37cc0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
37cd0 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
37ce0 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
37cf0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
37d00 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
37d10 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
37d20 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
37d30 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
37d40 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
37d50 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
37d60 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
37d70 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
37d80 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
37d90 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
37da0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
37db0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
37dc0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
37dd0 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
37de0 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
37df0 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
37e00 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
37e10 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
37e20 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
37e30 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
37e40 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
37e50 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
37e60 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
37e70 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
37e80 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
37e90 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
37ea0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
37eb0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
37ec0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
37ed0 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
37ee0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
37ef0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
37f00 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
37f10 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
37f20 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
37f30 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
37f40 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
37f50 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
37f60 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
37f70 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
37f80 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
37f90 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
37fa0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
37fb0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
37fc0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
37fd0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
37fe0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37ff0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
38000 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
38010 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
38020 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
38030 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
38040 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
38050 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
38060 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
38070 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
38080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38090 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
380a0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
380b0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
380c0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
380d0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
380e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
380f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
38100 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
38110 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
38120 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
38130 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
38140 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
38150 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
38160 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
38170 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
38180 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
38190 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
381a0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
381b0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
381c0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
381d0 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
381e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
381f0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
38200 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
38210 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
38220 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
38230 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
38240 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
38250 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
38260 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
38270 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
38280 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
38290 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
382a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
382b0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
382c0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
382d0 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
382e0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
382f0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
38300 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
38310 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
38320 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
38330 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
38340 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
38350 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
38360 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
38370 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
38380 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
38390 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
383a0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
383b0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
383c0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
383d0 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
383e0 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
383f0 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
38400 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
38410 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
38420 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
38430 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
38440 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
38450 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
38460 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
38470 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
38480 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
38490 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
384a0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
384b0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
384c0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
384d0 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
384e0 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
384f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
38500 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
38510 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
38520 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
38530 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
38540 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
38550 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
38560 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
38570 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
38580 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
38590 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
385a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
385b0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
385c0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
385d0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
385e0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
385f0 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
38600 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
38610 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
38620 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
38630 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
38640 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
38650 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
38660 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
38670 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
38680 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
38690 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
386a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
386b0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
386c0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
386d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
386e0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
386f0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
38700 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
38710 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
38720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
38730 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
38740 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
38750 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74  CALL sqlite3_set
38760 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
38770 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context