System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 8386044f2df2d7ad74c612c36d154d1bbaade28a:


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 33 2e 31 2e 20  ersion 3.8.3.1. 
00b0: 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c   By combining al
00c0: 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c  l the individual
00d0: 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e   C code files in
00e0: 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67  to this .** sing
00f0: 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74  le large file, t
0100: 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63  he entire code c
0110: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61  an be compiled a
0120: 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73  s a single trans
0130: 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20  lation.** unit. 
0140: 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e   This allows man
0150: 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64  y compilers to d
0160: 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  o optimizations 
0170: 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62  that would not b
0180: 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66  e.** possible if
0190: 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20   the files were 
01a0: 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74  compiled separat
01b0: 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63  ely.  Performanc
01c0: 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a  e improvements.*
01d0: 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20  * of 5% or more 
01e0: 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65  are commonly see
01f0: 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  n when SQLite is
0200: 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73   compiled as a s
0210: 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61  ingle.** transla
0220: 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a  tion unit..**.**
0230: 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c   This file is al
0240: 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f  l you need to co
0250: 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54  mpile SQLite.  T
0260: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20  o use SQLite in 
0270: 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d  other.** program
0280: 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73  s, you need this
0290: 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73   file and the "s
02a0: 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72  qlite3.h" header
02b0: 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e   file that defin
02c0: 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61  es.** the progra
02d0: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  mming interface 
02e0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  to the SQLite li
02f0: 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20  brary.  (If you 
0300: 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20  do not have .** 
0310: 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20  the "sqlite3.h" 
0320: 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68  header file at h
0330: 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69  and, you will fi
0340: 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64  nd a copy embedd
0350: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
0360: 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69   text of this fi
0370: 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20  le.  Search for 
0380: 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69  "Begin file sqli
0390: 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74  te3.h" to find t
03a0: 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74  he start.** of t
03b0: 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69  he embedded sqli
03c0: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c  te3.h header fil
03d0: 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  e.) Additional c
03e0: 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65  ode files may be
03f0: 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f   needed.** if yo
0400: 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72  u want a wrapper
0410: 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51   to interface SQ
0420: 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63  Lite with your c
0430: 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d  hoice of program
0440: 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65  ming.** language
0450: 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74  . The code for t
0460: 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d  he "sqlite3" com
0470: 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20  mand-line shell 
0480: 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20  is also in a.** 
0490: 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54  separate file. T
04a0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  his file contain
04b0: 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20  s only code for 
04c0: 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20  the core SQLite 
04d0: 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66  library..*/.#def
04e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20  ine SQLITE_CORE 
04f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
0500: 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a  _AMALGAMATION 1.
0510: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50  #ifndef SQLITE_P
0520: 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20  RIVATE.# define 
0530: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73  SQLITE_PRIVATE s
0540: 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66  tatic.#endif.#if
0550: 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a  ndef SQLITE_API.
0560: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0570: 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a  API.#endif./****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0590: 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20   file sqlite3.h 
05a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
05d0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
05e0: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
05f0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0600: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0610: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0620: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0630: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0640: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0650: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0660: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0670: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0680: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0690: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
06a0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
06b0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
06c0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
06d0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
06e0: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
06f0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72  *.** This header
0750: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68   file defines th
0760: 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  e interface that
0770: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
0780: 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20  ary.** presents 
0790: 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61  to client progra
07a0: 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63  ms.  If a C-func
07b0: 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c  tion, structure,
07c0: 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72   datatype,.** or
07d0: 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69   constant defini
07e0: 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70  tion does not ap
07f0: 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c  pear in this fil
0800: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a  e, then it is.**
0810: 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64   not a published
0820: 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20   API of SQLite, 
0830: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
0840: 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ange without.** 
0850: 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75  notice, and shou
0860: 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65  ld not be refere
0870: 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73  nced by programs
0880: 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65   that use SQLite
0890: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
08a0: 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20  the definitions 
08b0: 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73  that are in this
08c0: 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64   file are marked
08d0: 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65   as.** "experime
08e0: 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65  ntal".  Experime
08f0: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
0900: 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77  are normally new
0910: 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63  .** features rec
0920: 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53  ently added to S
0930: 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f  QLite.  We do no
0940: 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61  t anticipate cha
0950: 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72  nges.** to exper
0960: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
0970: 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74  es but reserve t
0980: 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65  he right to make
0990: 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a   minor changes.*
09a0: 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20  * if experience 
09b0: 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65  from use "in the
09c0: 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73   wild" suggest s
09d0: 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20  uch changes are 
09e0: 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  prudent..**.** T
09f0: 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61  he official C-la
0a00: 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d  nguage API docum
0a10: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c  entation for SQL
0a20: 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a  ite is derived.*
0a30: 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20  * from comments 
0a40: 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54  in this file.  T
0a50: 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20  his file is the 
0a60: 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f  authoritative so
0a70: 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53  urce.** on how S
0a80: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
0a90: 20 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20   are suppose to 
0aa0: 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  operate..**.** T
0ab0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20  he name of this 
0ac0: 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69  file under confi
0ad0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ae0: 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68  ent is "sqlite.h
0af0: 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b  .in"..** The mak
0b00: 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65  efile makes some
0b10: 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74   minor changes t
0b20: 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63  o this file (suc
0b30: 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a  h as inserting.*
0b40: 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75  * the version nu
0b50: 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65  mber) and change
0b60: 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73  s its name to "s
0b70: 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20  qlite3.h" as.** 
0b80: 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c  part of the buil
0b90: 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69  d process..*/.#i
0ba0: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
0bb0: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
0bc0: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
0bd0: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
0be0: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
0bf0: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
0c00: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
0c10: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
0c20: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
0c30: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
0c40: 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b  f 0.extern "C" {
0c50: 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20  .#endif.../*.** 
0c60: 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20  Add the ability 
0c70: 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74  to override 'ext
0c80: 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ern'.*/.#ifndef 
0c90: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20  SQLITE_EXTERN.# 
0ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
0cb0: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64  TERN extern.#end
0cc0: 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  if..#ifndef SQLI
0cd0: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0ce0: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0cf0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20  f.../*.** These 
0d00: 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65  no-op macros are
0d10: 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f   used in front o
0d20: 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  f interfaces to 
0d30: 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e  mark those.** in
0d40: 74 65 72 66 61 63 65 73 20 61 73 20 65 69 74 68  terfaces as eith
0d50: 65 72 20 64 65 70 72 65 63 61 74 65 64 20 6f 72  er deprecated or
0d60: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
0d70: 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  New applications
0d80: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75  .** should not u
0d90: 73 65 20 64 65 70 72 65 63 61 74 65 64 20 69 6e  se deprecated in
0da0: 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 20  terfaces - they 
0db0: 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20  are support for 
0dc0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
0dd0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
0de0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72    Application wr
0df0: 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  iters should be 
0e00: 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78  aware that.** ex
0e10: 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72  perimental inter
0e20: 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63  faces are subjec
0e30: 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70  t to change in p
0e40: 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a  oint releases..*
0e50: 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f  *.** These macro
0e60: 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76  s used to resolv
0e70: 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e  e to various kin
0e80: 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d  ds of compiler m
0e90: 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75  agic that.** wou
0ea0: 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e  ld generate warn
0eb0: 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65  ing messages whe
0ec0: 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64  n they were used
0ed0: 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63  .  But that.** c
0ee0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e  ompiler magic en
0ef0: 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e  ded up generatin
0f00: 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20  g such a flurry 
0f10: 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a  of bug reports.*
0f20: 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74  * that we have t
0f30: 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20  aken it all out 
0f40: 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f  and gone back to
0f50: 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a   using simple.**
0f60: 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f   noop macros..*/
0f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0f80: 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69  DEPRECATED.#defi
0f90: 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  ne SQLITE_EXPERI
0fa0: 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e  MENTAL../*.** En
0fb0: 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f  sure these symbo
0fc0: 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69  ls were not defi
0fd0: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76  ned by some prev
0fe0: 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65  ious header file
0ff0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
1000: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64  TE_VERSION.# und
1010: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
1020: 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  N.#endif.#ifdef 
1030: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1040: 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51  UMBER.# undef SQ
1050: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1060: 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  BER.#endif../*.*
1070: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1080: 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  ile-Time Library
1090: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
10a0: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
10b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20  LITE_VERSION] C 
10c0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
10d0: 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ro in the sqlite
10e0: 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76  3.h header.** ev
10f0: 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72  aluates to a str
1100: 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74  ing literal that
1110: 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76   is the SQLite v
1120: 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a  ersion in the.**
1130: 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20   format "X.Y.Z" 
1140: 77 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d  where X is the m
1150: 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ajor version num
1160: 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f  ber (always 3 fo
1170: 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e  r.** SQLite3) an
1180: 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72  d Y is the minor
1190: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
11a0: 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c  and Z is the rel
11b0: 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a  ease number.)^.*
11c0: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
11d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20  VERSION_NUMBER] 
11e0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
11f0: 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f  acro resolves to
1200: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77   an integer.** w
1210: 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58  ith the value (X
1220: 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30  *1000000 + Y*100
1230: 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20  0 + Z) where X, 
1240: 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65  Y, and Z are the
1250: 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73   same.** numbers
1260: 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45   used in [SQLITE
1270: 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20  _VERSION].)^.** 
1280: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
1290: 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e  ON_NUMBER for an
12a0: 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20  y given release 
12b0: 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  of SQLite will a
12c0: 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72  lso.** be larger
12d0: 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73   than the releas
12e0: 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20  e from which it 
12f0: 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74  is derived.  Eit
1300: 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65  her Y will.** be
1310: 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61   held constant a
1320: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63  nd Z will be inc
1330: 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65  remented or else
1340: 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Y will be incre
1350: 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20  mented.** and Z 
1360: 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f  will be reset to
1370: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e   zero..**.** Sin
1380: 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  ce version 3.6.1
1390: 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  8, SQLite source
13a0: 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73   code has been s
13b0: 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  tored in the.** 
13c0: 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f  <a href="http://
13d0: 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f  www.fossil-scm.o
13e0: 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66  rg/">Fossil conf
13f0: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65  iguration manage
1400: 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f  ment.** system</
1410: 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  a>.  ^The SQLITE
1420: 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f  _SOURCE_ID macro
1430: 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a   evaluates to.**
1440: 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
1450: 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72  identifies a par
1460: 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e  ticular check-in
1470: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
1480: 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75  thin its configu
1490: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
14a0: 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20  t system.  ^The 
14b0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
14c0: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
14d0: 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64  ins the date and
14e0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
14f0: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
1500: 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20  an SHA1.** hash 
1510: 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f  of the entire so
1520: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
1530: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1540: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1550: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
1560: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1570: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
1580: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
1590: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
15a0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
15b0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64  rce_id()]..*/.#d
15c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
15d0: 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 38  SION        "3.8
15e0: 2e 33 2e 31 22 0a 23 64 65 66 69 6e 65 20 53 51  .3.1".#define SQ
15f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1600: 42 45 52 20 33 30 30 38 30 30 33 0a 23 64 65 66  BER 3008003.#def
1610: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1620: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 34 2d  E_ID      "2014-
1630: 30 32 2d 31 31 20 30 33 3a 35 35 3a 33 33 20 33  02-11 03:55:33 3
1640: 31 31 31 64 66 37 31 62 32 61 36 62 65 66 30 38  111df71b2a6bef08
1650: 63 66 33 37 63 36 65 33 35 30 66 35 61 63 63 63  cf37c6e350f5accc
1660: 35 30 36 66 39 65 62 22 0a 0a 2f 2a 0a 2a 2a 20  506f9eb"../*.** 
1670: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1680: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
1690: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
16a0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
16b0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
16c0: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
16d0: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
16e0: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
16f0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1700: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1710: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1720: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1730: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1740: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1750: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
1760: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
1770: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
1780: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
1790: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
17a0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
17b0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
17c0: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
17d0: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
17e0: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
17f0: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1800: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1810: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1820: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1830: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1840: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1850: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
1860: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
1870: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
1880: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
1890: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
18a0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
18b0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18c0: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
18d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
18e0: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
18f0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1900: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1910: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1920: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1930: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1940: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1950: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
1960: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
1970: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
1980: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1990: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
19a0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
19b0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
19c0: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
19d0: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
19e0: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
19f0: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1a00: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1a10: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1a30: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1a40: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1a50: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
1a60: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
1a70: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
1a80: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
1a90: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
1aa0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
1ab0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1ac0: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1ad0: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1ae0: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1af0: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1b00: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1b10: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1b20: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1b30: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1b40: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1b50: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
1b60: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
1b70: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
1b80: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
1b90: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
1ba0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
1bb0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1bc0: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1bd0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1be0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1bf0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1c00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1c10: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1c20: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1c30: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1c40: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  I const char sql
1c50: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d  ite3_version[] =
1c60: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b   SQLITE_VERSION;
1c70: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
1c80: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1c90: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29  libversion(void)
1ca0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1cb0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1cc0: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
1cd0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1ce0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1cf0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1d00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d10: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1d20: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
1d30: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1d40: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1d50: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1d60: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1d70: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1d80: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1d90: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1da0: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1db0: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1dc0: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1dd0: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
1de0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
1df0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
1e00: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
1e10: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
1e20: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1e30: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1e40: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1e50: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1e60: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1e70: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1e80: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1e90: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1ea0: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1eb0: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1ec0: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1ed0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
1ee0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
1ef0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
1f00: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
1f10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1f20: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
1f30: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1f40: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1f50: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1f60: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1f70: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1f80: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1f90: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1fa0: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1fb0: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1fc0: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1fd0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1fe0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
1ff0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
2000: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
2010: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
2020: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
2030: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
2040: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
2050: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
2060: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
2070: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
2080: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
2090: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
20a0: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
20b0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
20c0: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
20d0: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
20e0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
20f0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2100: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
2110: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  AGS.SQLITE_API i
2120: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
2130: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
2140: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
2150: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
2160: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2170: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
2180: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
2190: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
21a0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
21b0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
21c0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
21d0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21e0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
21f0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2200: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
2210: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
2220: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2230: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
2240: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
2250: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
2270: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
2280: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
2290: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
22a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
22b0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
22c0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
22d0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
22e0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
22f0: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
2300: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
2310: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
2320: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
2330: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
2340: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2350: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
2360: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
2370: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
2380: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
2390: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
23a0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
23b0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
23c0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
23d0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
23e0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
23f0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
2400: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
2410: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
2420: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
2430: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
2440: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
2450: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
2460: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
2470: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
2480: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
2490: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
24a0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
24b0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
24c0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
24d0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
24e0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
24f0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2500: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2510: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2520: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2530: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2540: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2550: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2560: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2570: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2580: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
2590: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
25a0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
25b0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
25c0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
25d0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
25e0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
25f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2600: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2610: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2620: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2630: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2640: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2650: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2660: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2670: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2680: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
2690: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
26a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
26b0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
26c0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
26d0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
26e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
26f0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2700: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2710: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
2720: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2730: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
2740: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
2750: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
2760: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2770: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
2780: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
2790: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
27a0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
27b0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
27c0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
27d0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
27e0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
27f0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2800: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
2810: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
2820: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
2830: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
2840: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
2850: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
2860: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
2870: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2880: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
2890: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28a0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
28b0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
28c0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
28d0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
28e0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
28f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2900: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2910: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2920: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2930: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2940: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2950: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
2960: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
2970: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
2980: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
2990: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
29a0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
29b0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
29c0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
29d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
29e0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
29f0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2a00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2a10: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2a20: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2a30: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2a40: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
2a50: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
2a60: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
2a70: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
2a80: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
2a90: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
2aa0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
2ab0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ac0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2ad0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2ae0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2af0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2b00: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2b10: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2b20: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2b30: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2b40: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2b50: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2b60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b70: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
2b80: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
2b90: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
2ba0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
2bb0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
2bc0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
2bd0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2be0: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2bf0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2c00: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2c10: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2c20: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2c30: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2c40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2c50: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2c60: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2c70: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
2c80: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
2c90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
2ca0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2cb0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
2cc0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
2cd0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2ce0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2cf0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d00: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2d10: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2d20: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2d30: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2d40: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2d50: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2d60: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2d70: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
2d80: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
2d90: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2da0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
2db0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2dc0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
2dd0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2de0: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2df0: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2e00: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2e10: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2e20: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2e30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2e40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2e50: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2e60: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2e70: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
2e80: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2e90: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2ea0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2eb0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2ec0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2ed0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2ee0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2ef0: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2f00: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2f10: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2f20: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2f30: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2f40: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2f50: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2f60: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2f70: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2f80: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2f90: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2fa0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2fb0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2fc0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2fd0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2fe0: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2ff0: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
3000: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
3010: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
3020: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
3030: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
3040: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
3050: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
3060: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
3070: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
3080: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
3090: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
30a0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
30b0: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20  e_v2() routines 
30c0: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a  are destructors.
30d0: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  ** for the [sqli
30e0: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
30f0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
3100: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
3110: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
3120: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
3130: 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  K if.** the [sql
3140: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3150: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
3160: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
3170: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
3180: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
3190: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
31a0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
31b0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
31c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
31d0: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
31e0: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
31f0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
3200: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
3210: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
3220: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
3230: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
3240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
3250: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
3260: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
3270: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
3280: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
3290: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
32a0: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
32b0: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75  tements.** and u
32c0: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
32d0: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
32e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
32f0: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
3300: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
3310: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
3320: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
3330: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
3340: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
3350: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
3360: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
3370: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
3380: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
3390: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
33a0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
33b0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
33c0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
33d0: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
33e0: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
33f0: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
3400: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
3410: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
3420: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
3430: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
3440: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
3450: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
3460: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
3470: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
3480: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
3490: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
34a0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34b0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
34c0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
34d0: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
34e0: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
34f0: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3500: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3510: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3520: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3530: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3540: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3550: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
3560: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
3570: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3580: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
3590: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35a0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
35b0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
35c0: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
35d0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
35e0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
35f0: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3600: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3610: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3620: 53 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68  SQLITE_OK but th
3630: 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  e deallocation.*
3640: 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69  * of resources i
3650: 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  s deferred until
3660: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
3670: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
3680: 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61  B handles],.** a
3690: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  nd [sqlite3_back
36a0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20  up] objects are 
36b0: 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a  also destroyed..
36c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71  **.** ^If an [sq
36d0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
36e0: 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65   destroyed while
36f0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
3700: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74  s open,.** the t
3710: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75  ransaction is au
3720: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
3730: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
3740: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
3750: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
3760: 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (C)] and [sqlite
3770: 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a  3_close_v2(C)].*
3780: 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
3790: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
37a0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
37b0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
37c0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
37d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
37e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
37f0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
3800: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
3810: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
3820: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
3830: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
3840: 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71  e3_close() or sq
3850: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
3860: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
3870: 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  nter.** argument
3880: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
3890: 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  o-op..*/.SQLITE_
38a0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38b0: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b  close(sqlite3*);
38c0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
38d0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
38e0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
38f0: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3900: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3910: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3920: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3930: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
3940: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
3950: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
3960: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3970: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3980: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3990: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
39a0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
39b0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
39c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
39d0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
39e0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
39f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3a00: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
3a10: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
3a20: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
3a30: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
3a40: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
3a50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
3a60: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3a70: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3a80: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3a90: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3aa0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3ab0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3ac0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3ad0: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3ae0: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3af0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3b00: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
3b10: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
3b20: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
3b30: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
3b40: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
3b50: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
3b60: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3b70: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3b80: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3b90: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3ba0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3bb0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3bc0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3bd0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3be0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3bf0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3c00: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
3c10: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
3c20: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
3c30: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
3c40: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
3c50: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
3c60: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3c70: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3ca0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3cb0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3cc0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3cd0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3ce0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3cf0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d00: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
3d10: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
3d20: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
3d30: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3d40: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3d50: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
3d60: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3d70: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3d80: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3d90: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3da0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3db0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3dc0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3dd0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3de0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3df0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3e00: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
3e10: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e20: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3e30: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3e40: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3e50: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
3e60: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3e70: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3e80: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3e90: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3ea0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3eb0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3ec0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3ed0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3ee0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3ef0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3f00: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
3f10: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3f20: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3f30: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3f40: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
3f50: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3f60: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3f70: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3f80: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3f90: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3fa0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3fb0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3fc0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3fd0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3fe0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3ff0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
4000: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
4010: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
4020: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
4030: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
4040: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
4050: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
4060: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
4070: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
4080: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
4090: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
40a0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
40b0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
40c0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
40d0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
40e0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
40f0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
4100: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
4110: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
4120: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
4130: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
4140: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
4150: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
4160: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
4170: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
4180: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
4190: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
41a0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
41b0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
41c0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
41d0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
41e0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
41f0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
4200: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
4210: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
4220: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
4230: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
4240: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
4250: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
4260: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
4270: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
4280: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
4290: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
42a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
42b0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
42c0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
42d0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
42e0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
42f0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
4300: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
4310: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
4320: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
4330: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
4340: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
4350: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
4360: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4370: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
4380: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
4390: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
43a0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
43b0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
43c0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
43d0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
43e0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
43f0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
4400: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
4410: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
4420: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
4430: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
4440: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
4450: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
4460: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4470: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
4480: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
4490: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
44a0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
44b0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
44c0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
44d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
44e0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
44f0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4500: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4510: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4520: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
4530: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
4540: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4550: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4560: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4570: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
4580: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4590: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
45a0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
45b0: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
45c0: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
45d0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
45e0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
45f0: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4600: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4610: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ul>.*/.SQL
4620: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
4630: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
4640: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
4650: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4660: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
4670: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
4680: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
4690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
46a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
46b0: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
46c0: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c  d */.  int (*cal
46d0: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
46e0: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c  ,char**,char**),
46f0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75    /* Callback fu
4700: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
4710: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
4720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4730: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72         /* 1st ar
4740: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61  gument to callba
4750: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  ck */.  char **e
4760: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20  rrmsg           
4770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4780: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
4790: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
47a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
47b0: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73  EF: Result Codes
47c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
47d0: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
47e0: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
47f0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4800: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72  {result code} {r
4810: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
4820: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4830: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4840: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
4850: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4860: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4870: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4880: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
4890: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
48a0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
48b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
48c0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
48d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
48e0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
48f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
4900: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4910: 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c   codes],.** [sql
4920: 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
4930: 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45  flict()] [SQLITE
4940: 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75  _ROLLBACK | resu
4950: 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64  lt codes]..*/.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
4970: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
4980: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
4990: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
49a0: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
49b0: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
49c0: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
49d0: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
49e0: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
49f0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
4a00: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
4a10: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
4a20: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
4a30: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
4a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
4a50: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
4a60: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
4a70: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
4a90: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
4aa0: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
4ab0: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
4ac0: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
4ad0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
4ae0: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
4af0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
4b00: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4b10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
4b20: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
4b30: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
4b40: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
4b70: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
4b80: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
4b90: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
4ba0: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
4bb0: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
4bc0: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4be0: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
4bf0: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
4c00: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
4c10: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
4c20: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
4c30: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
4c40: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
4c50: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
4c60: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
4c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4c80: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
4c90: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4ca0: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
4cb0: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
4cc0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
4cd0: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
4ce0: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
4cf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
4d00: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
4d20: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
4d30: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
4d40: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
4d50: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
4d60: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
4d70: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
4d80: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
4d90: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4db0: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
4dc0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
4dd0: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
4de0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4df0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
4e00: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
4e10: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
4e20: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
4e30: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4e40: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4e50: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4e70: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4e80: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
4e90: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
4ea0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
4eb0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
4ec0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
4ed0: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
4ee0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
4ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4f00: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
4f10: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
4f20: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
4f30: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4f40: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4f50: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4f60: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4f70: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4f80: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
4f90: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
4fa0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
4fb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4fc0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
4fd0: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
4fe0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
5000: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
5010: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
5020: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
5030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5040: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
5050: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
5060: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
5070: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
5080: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
5090: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
50a0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
50b0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
50c0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
50d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
50e0: 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37  E_NOTICE      27
50f0: 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69     /* Notificati
5100: 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ons from sqlite3
5110: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
5120: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5130: 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72       28   /* War
5140: 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74  nings from sqlit
5150: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
5160: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
5170: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
5180: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
5190: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
51a0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
51b0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
51c0: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
51d0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
51e0: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
51f0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
5200: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
5210: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
5220: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
5230: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
5240: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
5250: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
5260: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
5270: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
5280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
5290: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
52a0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
52b0: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
52c0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
52d0: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
52e0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
52f0: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
5300: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
5310: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
5320: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
5330: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
5340: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
5350: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
5360: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
5370: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
5380: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
5390: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
53a0: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
53b0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
53c0: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
53d0: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
53e0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
53f0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
5400: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
5410: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
5420: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
5430: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
5440: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
5450: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
5460: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
5470: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
5480: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
5490: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
54a0: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
54b0: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
54c0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
54d0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
54e0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
54f0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5500: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
5510: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
5520: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
5530: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
5540: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
5550: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
5560: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
5570: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
5580: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69  ult codes will i
5590: 6e 63 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20  ncrease.** over 
55a0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
55b0: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
55c0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
55d0: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
55e0: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
55f0: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
5600: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
5610: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
5620: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
5630: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
5640: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
5650: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
5660: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
5670: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
5680: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
5690: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
56b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56c0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
56d0: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
56e0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
56f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5700: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
5710: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5720: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
5730: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5740: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
5750: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5760: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
5770: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5780: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
5790: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57a0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57c0: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
57d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57e0: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5800: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5820: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
5830: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5840: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
5850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5860: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
5870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5880: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
5890: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58a0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
58b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
58c0: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
58d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
58e0: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
58f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5900: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
5910: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5920: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
5930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5940: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
5950: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5960: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
5970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5980: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
5990: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
59a0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
59b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
59c0: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
59d0: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
59e0: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5a00: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
5a10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5a20: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
5a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5a40: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5a50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5a60: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
5a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5a80: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
5a90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5aa0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
5ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5ac0: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
5ad0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5ae0: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5b00: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5b10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5b20: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
5b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5b40: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
5b50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5b60: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5b80: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5b90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5ba0: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5bc0: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5bd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5be0: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5c00: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20  R_DELETE_NOENT  
5c10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5c20: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65  R | (23<<8)).#de
5c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5c40: 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  R_MMAP          
5c50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5c60: 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65  R | (24<<8)).#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5c80: 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20  R_GETTEMPPATH   
5c90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5ca0: 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65  R | (25<<8)).#de
5cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5cc0: 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  R_CONVPATH      
5cd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5ce0: 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65  R | (26<<8)).#de
5cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5d00: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
5d10: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5d20: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
5d30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5d40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5d50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5d60: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5d80: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5d90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5da0: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5dc0: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5dd0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5de0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5df0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5e00: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5e10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5e20: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5e30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5e40: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5e50: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5e60: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e80: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5e90: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5ea0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5eb0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5ec0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5ed0: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5ee0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5ef0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f00: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5f10: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5f20: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5f30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5f40: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5f50: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
5f60: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5f70: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5f90: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
5fa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5fb0: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
5fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5fd0: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
5fe0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5ff0: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
6000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6010: 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20  ABORT_ROLLBACK  
6020: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
6030: 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a  ABORT | (2<<8)).
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6050: 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20  ONSTRAINT_CHECK 
6060: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
6070: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c  ONSTRAINT | (1<<
6080: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6090: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f  TE_CONSTRAINT_CO
60a0: 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49  MMITHOOK   (SQLI
60b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
60c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
60d0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
60e0: 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28  T_FOREIGNKEY   (
60f0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6100: 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  T | (3<<8)).#def
6110: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6120: 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20  RAINT_FUNCTION  
6130: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
6140: 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a  RAINT | (4<<8)).
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6160: 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c  ONSTRAINT_NOTNUL
6170: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  L      (SQLITE_C
6180: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c  ONSTRAINT | (5<<
6190: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
61a0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52  TE_CONSTRAINT_PR
61b0: 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49  IMARYKEY   (SQLI
61c0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
61d0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
61e0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
61f0: 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28  T_TRIGGER      (
6200: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6210: 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  T | (7<<8)).#def
6220: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6230: 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20  RAINT_UNIQUE    
6240: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
6250: 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a  RAINT | (8<<8)).
6260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6270: 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20  ONSTRAINT_VTAB  
6280: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
6290: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c  ONSTRAINT | (9<<
62a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
62b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f  TE_CONSTRAINT_RO
62c0: 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  WID        (SQLI
62d0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28  TE_CONSTRAINT |(
62e0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
62f0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
6300: 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28  COVER_WAL      (
6310: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
6320: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6330: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
6340: 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28  COVER_ROLLBACK (
6350: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
6360: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
6370: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41  SQLITE_WARNING_A
6380: 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28  UTOINDEX       (
6390: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c  SQLITE_WARNING |
63a0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
63b0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
63c0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
63d0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
63e0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
63f0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6400: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6410: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6420: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6430: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6440: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6450: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6460: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6470: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
6480: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6490: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
64a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
64b0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
64c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6510: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6520: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6530: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6540: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6550: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6560: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6580: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
6590: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
65a0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
65b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65c0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
65d0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
65e0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6610: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6620: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6670: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6690: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
66a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
66b0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
66c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
66d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66e0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
66f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6700: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6710: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6720: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6730: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6740: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6750: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6760: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6770: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
6780: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
6790: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67a0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
67b0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
67c0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
67d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67e0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
67f0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6800: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6810: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6820: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6830: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6840: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6870: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
6880: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6890: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68a0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
68b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
68c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68f0: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6900: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6910: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6920: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6930: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6940: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6950: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6960: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6970: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6990: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
69a0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
69b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
69c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
69d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
69e0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
69f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6a00: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6a10: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6a20: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6a40: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6a50: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6a60: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6a70: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
6a80: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6a90: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6aa0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6ab0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6ac0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6ad0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6ae0: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6af0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6b00: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6b10: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6b20: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6b30: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6b40: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6b50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6b60: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6b70: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6b80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b90: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ba0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6bb0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6bc0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6bd0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6be0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6bf0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6c00: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6c10: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6c20: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6c30: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6c40: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6c50: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6c60: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6c70: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6c80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6c90: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6ca0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6cb0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6cc0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6cd0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6ce0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6cf0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6d00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6d10: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6d20: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6d30: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6d40: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6d50: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6d60: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6d70: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6d80: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6d90: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6da0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6db0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6dc0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6dd0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6de0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6df0: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6e00: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6e10: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6e20: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6e30: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6e40: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6e50: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6e60: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6e70: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6e80: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6e90: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6ea0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6eb0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6ec0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6ed0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6ef0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6f00: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6f10: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  te that a file c
6f20: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6f30: 20 77 68 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23   when open..*/.#
6f40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6f50: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6f60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6f70: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6f80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6f90: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6fa0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6fc0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6fd0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6fe0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6ff0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7000: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
7010: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
7020: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7030: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
7040: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
7050: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7060: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
7070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
7080: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
7090: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
70a0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
70b0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
70c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
70d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
70e0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
70f0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
7100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7110: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
7120: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
7130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7140: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
7150: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7160: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
7170: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7180: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
7190: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
71a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
71b0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
71c0: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
71d0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
71e0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
71f0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
7200: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
7210: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
7220: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
7230: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
7240: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
7250: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
7260: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
7270: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
7280: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
7290: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
72a0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
72b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
72c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
72d0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
72e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
72f0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
7300: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
7310: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
7320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7330: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
7340: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
7350: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
7360: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
7370: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7380: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
7390: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
73a0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
73b0: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
73c0: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
73d0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
73e0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
73f0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7400: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
7410: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
7420: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
7430: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
7440: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
7450: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
7460: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7470: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
7480: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
7490: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
74a0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
74b0: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
74c0: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
74d0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
74e0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
74f0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
7500: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
7510: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
7520: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
7530: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
7540: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
7550: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7560: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
7570: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7580: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7590: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
75a0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
75b0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
75c0: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
75d0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
75e0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
75f0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
7600: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7610: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
7620: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
7630: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7640: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
7650: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7660: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
7670: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7680: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7690: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
76a0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
76b0: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
76c0: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
76d0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
76e0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
76f0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
7700: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
7710: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7720: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
7730: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7740: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7750: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7760: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7770: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7780: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7790: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
77a0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
77b0: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
77c0: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
77d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
77e0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
77f0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
7800: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
7810: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7820: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7830: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7840: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7850: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7860: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7870: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7880: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7890: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
78a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
78b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
78c0: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
78d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
78e0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
78f0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
7900: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7910: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
7920: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7930: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7940: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7950: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7960: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7970: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7980: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7990: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
79a0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
79b0: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
79c0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
79d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
79e0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
79f0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
7a00: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
7a10: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
7a20: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7a30: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7a40: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7a50: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7a60: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7a70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7a80: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7a90: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7aa0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7ab0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7ac0: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7ad0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7ae0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7af0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
7b00: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
7b10: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
7b20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7b30: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7b40: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7b50: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7b60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7b70: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7b80: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7b90: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7ba0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7bb0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7bc0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7bd0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7be0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7bf0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
7c00: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
7c10: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
7c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7c30: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7c40: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7c50: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7c60: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7c70: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7c80: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7c90: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7ca0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7cb0: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7cc0: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7cd0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7ce0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7cf0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
7d00: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7d10: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
7d20: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7d30: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7d40: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7d50: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7d60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7d70: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7d80: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7d90: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7da0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7db0: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7dc0: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7dd0: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7de0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7df0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
7e00: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
7e10: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
7e20: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7e30: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7e40: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7e70: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7e80: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7e90: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7ea0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7eb0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7ec0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7ed0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7ee0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7ef0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7f00: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
7f10: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
7f20: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7f30: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7f40: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7f50: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7f60: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7f70: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7f80: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7f90: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7fa0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7fb0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7fc0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7fd0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7fe0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7ff0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
8000: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
8010: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
8030: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
8040: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8050: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
8060: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8070: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
8090: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
80a0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
80b0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
80c0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
80d0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
80e0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
80f0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
8100: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
8110: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
8120: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
8130: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
8140: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
8150: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
8160: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
8170: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
8180: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
8190: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
81a0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
81b0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
81c0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
81d0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
81e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
81f0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
8200: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
8210: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
8220: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
8230: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8240: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
8250: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
8260: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
8270: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8280: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
8290: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
82a0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
82b0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
82c0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
82d0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
82e0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
82f0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
8300: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
8310: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
8320: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
8330: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
8340: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
8350: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
8360: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
8370: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
8380: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
8390: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
83a0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
83b0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
83c0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
83d0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
83e0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
83f0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
8400: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
8410: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
8420: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
8430: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
8440: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
8450: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
8460: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
8470: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
8480: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
8490: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
84a0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
84b0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
84c0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
84d0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
84e0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
84f0: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
8500: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8510: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
8520: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
8530: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
8540: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
8550: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
8560: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
8570: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
8580: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
8590: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
85a0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
85b0: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
85c0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
85d0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
85e0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
85f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
8600: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
8610: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
8620: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
8630: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
8640: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
8650: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
8660: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
8670: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
8680: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
8690: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
86a0: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
86b0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
86c0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
86d0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
86e0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
86f0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
8700: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8710: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8720: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
8730: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8740: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
8750: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8760: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
8770: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8780: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
8790: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
87a0: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
87b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
87c0: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
87d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
87e0: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
87f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8800: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
8810: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8820: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
8830: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8840: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
8850: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8860: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
8870: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8880: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8890: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
88a0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
88b0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
88c0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
88d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
88e0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
88f0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
8900: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
8910: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
8920: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
8930: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
8940: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
8950: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
8960: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
8970: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
8980: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8990: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
89a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
89b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
89c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
89d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
89e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
89f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
8a00: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
8a10: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
8a20: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
8a30: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
8a40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8a50: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
8a60: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
8a70: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
8a80: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
8a90: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
8aa0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
8ab0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
8ac0: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
8ad0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
8ae0: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
8af0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
8b00: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
8b10: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
8b20: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
8b30: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
8b40: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8b50: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
8b60: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
8b70: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
8b80: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
8b90: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
8ba0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
8bb0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
8bc0: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
8bd0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
8be0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8bf0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8c00: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
8c10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
8c20: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
8c30: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8c50: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
8c60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
8c70: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
8c80: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c90: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
8ca0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
8cb0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
8cc0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8cd0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8ce0: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
8cf0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
8d00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8d10: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
8d20: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
8d30: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
8d40: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8d50: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8d60: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8d70: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
8d80: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
8d90: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8da0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
8db0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8dc0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
8dd0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8df0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
8e00: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
8e10: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
8e20: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
8e30: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
8e40: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
8e50: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8e60: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
8e70: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
8e80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8e90: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8ea0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8eb0: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
8ec0: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
8ed0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ee0: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
8ef0: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
8f00: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
8f10: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
8f20: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
8f30: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
8f40: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
8f50: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
8f60: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8f70: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
8f80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f90: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
8fa0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8fb0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8fc0: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
8fd0: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71  int (*xFetch)(sq
8fe0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8ff0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
9000: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64  , int iAmt, void
9010: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a   **pp);.  int (*
9020: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65  xUnfetch)(sqlite
9030: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
9040: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f  _int64 iOfst, vo
9050: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74  id *p);.  /* Met
9060: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
9070: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
9080: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   3 */.  /* Addit
9090: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
90a0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
90b0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
90c0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
90d0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
90e0: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
90f0: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  es.**.** These i
9100: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
9110: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
9120: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
9130: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
9140: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
9150: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
9160: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
9170: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9180: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
9190: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
91a0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
91b0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
91c0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
91d0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
91e0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
91f0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9200: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
9210: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
9220: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
9230: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
9240: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
9250: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
9260: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
9270: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
9280: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
9290: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
92a0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
92b0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
92c0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
92d0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
92e0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
92f0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
9300: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
9310: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
9320: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
9330: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
9340: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c   defined..** <ul
9350: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  >.** <li>[[SQLIT
9360: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9370: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9380: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9390: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
93a0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
93b0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
93c0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
93d0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
93e0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
93f0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
9400: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
9410: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
9420: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
9430: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9440: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9450: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9460: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9470: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9480: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9490: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
94a0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
94b0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
94c0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
94d0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
94e0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
94f0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
9500: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9510: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
9520: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9530: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9540: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9550: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9560: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9570: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9580: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9590: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
95a0: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
95b0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
95c0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
95d0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
95e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95f0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
9600: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
9610: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9620: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9630: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9640: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9650: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9660: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9670: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9680: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9690: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
96a0: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
96b0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
96c0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
96d0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
96e0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
96f0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
9700: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9710: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9720: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9730: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9740: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9750: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9760: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9780: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9790: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
97a0: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
97b0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
97c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
97d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
97e0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
97f0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
9800: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
9810: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9820: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9830: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9840: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9850: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9860: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9880: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9890: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
98a0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
98b0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
98c0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
98d0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
98e0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
98f0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
9900: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9910: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9920: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9930: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9940: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9950: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9960: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9970: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9980: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9990: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
99a0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
99b0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
99c0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
99d0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
99e0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
99f0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
9a00: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9a10: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9a20: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9a30: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9a40: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9a50: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9a60: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9a70: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9a80: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9a90: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9aa0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9ab0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9ac0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9ad0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9ae0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
9af0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
9b00: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9b10: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9b20: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9b30: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9b40: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9b50: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9b60: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9b70: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9b80: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9b90: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9ba0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9bb0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9bc0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9bd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9be0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
9bf0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9c00: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9c10: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9c20: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9c30: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9c40: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9c50: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9c60: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9c70: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9c80: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9c90: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9ca0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9cb0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9cc0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9cd0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9ce0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
9cf0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
9d00: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9d10: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9d20: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9d30: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9d40: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9d50: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9d60: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9d70: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9d80: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9d90: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9da0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9db0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9dc0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9dd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
9de0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
9df0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9e00: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9e10: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
9e20: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
9e30: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
9e40: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9e50: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9e60: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9e70: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9e80: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9e90: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9ea0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
9eb0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
9ec0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
9ed0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
9ee0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
9ef0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
9f00: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
9f10: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
9f20: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
9f30: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
9f40: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
9f50: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
9f60: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
9f70: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9f80: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9f90: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9fa0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9fb0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9fc0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9fd0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9fe0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
9ff0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
a000: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
a010: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
a020: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
a030: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
a040: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a050: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
a060: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
a070: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
a080: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
a090: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
a0a0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
a0b0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
a0c0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
a0d0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
a0e0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
a0f0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
a100: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
a110: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
a120: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
a130: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
a140: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
a150: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
a160: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
a170: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
a180: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
a190: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
a1a0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
a1b0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
a1c0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
a1d0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
a1e0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
a1f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
a210: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
a220: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a230: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
a240: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a250: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a260: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
a270: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
a280: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
a290: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
a2a0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
a2b0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
a2c0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
a2d0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
a2e0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
a2f0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
a300: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
a310: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
a320: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
a330: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
a340: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
a350: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a360: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
a370: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
a380: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
a390: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
a3a0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
a3b0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
a3c0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
a3d0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
a3e0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
a3f0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
a400: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
a410: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
a420: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
a430: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
a440: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
a450: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
a460: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
a470: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
a480: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
a490: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
a4a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a4b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4c0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a4d0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a4e0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a4f0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a500: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a510: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
a520: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a530: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a540: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a550: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a560: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a570: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a580: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a590: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a5a0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a5b0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a5d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a5e0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a5f0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a600: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a610: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a620: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a630: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a640: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a650: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a660: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a670: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a680: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a690: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a6a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a6b0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a6c0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a6d0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a6e0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a6f0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a700: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a710: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a720: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a730: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a740: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a750: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a760: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a770: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a780: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a790: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a7a0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a7b0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a7c0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a7d0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
a7e0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
a7f0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a800: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a810: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a820: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
a830: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a840: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
a850: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
a860: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
a870: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
a880: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
a890: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
a8a0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
a8b0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
a8c0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
a8d0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
a8e0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
a8f0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
a900: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
a910: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
a920: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
a930: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a940: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
a950: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a960: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
a970: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
a980: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
a990: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
a9a0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
a9b0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
a9c0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
a9d0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
a9e0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
a9f0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
aa00: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
aa10: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
aa20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
aa30: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
aa40: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
aa50: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
aa60: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
aa70: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
aa80: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
aa90: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
aaa0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
aab0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
aac0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
aad0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
aae0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
aaf0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
ab00: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
ab10: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
ab20: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
ab30: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
ab40: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
ab50: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
ab60: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
ab70: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
ab80: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
ab90: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
aba0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
abb0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
abc0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
abd0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
abe0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
abf0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
ac00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ac10: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
ac20: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
ac30: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
ac40: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
ac50: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ac60: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
ac70: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
ac80: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
ac90: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
aca0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
acb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
acc0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
acd0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
ace0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
acf0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
ad00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ad10: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ad20: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
ad30: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
ad40: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
ad50: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
ad60: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
ad70: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
ad80: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ad90: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
ada0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
adb0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
adc0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
add0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
ade0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
adf0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
ae00: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
ae10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ae20: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
ae30: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
ae40: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
ae50: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
ae60: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
ae70: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
ae80: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
ae90: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
aea0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
aeb0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
aec0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
aed0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
aee0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
aef0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
af00: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
af10: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
af20: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
af30: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
af40: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
af50: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
af60: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
af70: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
af80: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
af90: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
afa0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
afb0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
afc0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
afd0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
afe0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
aff0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
b000: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
b010: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
b020: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
b030: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
b040: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
b050: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
b060: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b070: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b080: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
b090: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
b0a0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
b0b0: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
b0c0: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
b0d0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
b0e0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
b0f0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
b100: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
b110: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
b120: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
b130: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
b140: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
b150: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b160: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b170: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
b180: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
b190: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
b1a0: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
b1b0: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
b1c0: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
b1d0: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
b1e0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
b1f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b200: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b210: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
b220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b230: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
b240: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
b250: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
b260: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
b270: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
b280: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
b290: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
b2a0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
b2b0: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
b2c0: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
b2d0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
b2e0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
b2f0: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
b300: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
b310: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
b320: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
b330: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
b340: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
b350: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
b360: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
b370: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
b380: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
b390: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
b3a0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
b3b0: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
b3c0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
b3d0: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
b3e0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
b3f0: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
b400: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
b410: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
b420: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
b430: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
b440: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
b450: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
b460: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
b470: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
b480: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
b490: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
b4a0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
b4b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b4c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b4d0: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
b4e0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
b4f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b500: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
b510: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
b520: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
b530: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
b540: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
b550: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
b560: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
b570: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
b580: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
b590: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
b5a0: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
b5b0: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
b5c0: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
b5d0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
b5e0: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
b5f0: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
b600: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
b610: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
b620: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
b630: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b640: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
b650: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
b660: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
b670: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
b680: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
b690: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
b6a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b6c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b6d0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b6e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b6f0: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
b700: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
b710: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b720: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
b730: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
b740: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
b750: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b760: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b770: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
b780: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
b790: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
b7a0: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
b7b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
b7c0: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
b7d0: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
b7e0: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
b7f0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
b800: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
b810: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
b820: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
b830: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
b840: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
b850: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
b860: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
b870: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
b880: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
b890: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
b8a0: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
b8b0: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
b8c0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b8d0: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
b8e0: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
b8f0: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
b900: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b910: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
b920: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b930: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
b940: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
b950: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
b960: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
b970: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
b980: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
b990: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
b9a0: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
b9b0: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
b9c0: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
b9d0: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
b9e0: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
b9f0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
ba00: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
ba10: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
ba20: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
ba30: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
ba40: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
ba50: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
ba60: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
ba70: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
ba80: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
ba90: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
baa0: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
bab0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
bad0: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
bae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
baf0: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
bb00: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
bb10: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
bb20: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
bb30: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
bb40: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
bb50: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
bb60: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
bb70: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
bb80: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
bb90: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
bba0: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
bbb0: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
bbc0: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
bbd0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
bbe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bbf0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
bc00: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
bc10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
bc20: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bc30: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
bc40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
bc50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
bc60: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
bc70: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
bc80: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
bc90: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
bca0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bcb0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
bcc0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
bcd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
bce0: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
bcf0: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
bd00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
bd10: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
bd20: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
bd30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
bd40: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
bd50: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
bd60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
bd70: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
bd80: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
bd90: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
bda0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
bdb0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
bdc0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
bdd0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
bde0: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
bdf0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
be00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
be10: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
be20: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
be30: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
be40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
be60: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
be70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
be80: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
be90: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
bea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
beb0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bec0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
bed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bee0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
bef0: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
bf00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf10: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
bf20: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
bf30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bf40: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
bf50: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
bf60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bf70: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
bf80: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
bf90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
bfa0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
bfb0: 20 20 20 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20        22../*.** 
bfc0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
bfd0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
bfe0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
bff0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
c000: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
c010: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
c020: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
c030: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
c040: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
c050: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
c060: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
c070: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
c080: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
c090: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
c0a0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
c0b0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
c0c0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
c0d0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
c0e0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
c0f0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c100: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
c110: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c120: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
c130: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
c140: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c150: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
c160: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
c170: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
c180: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c190: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c1a0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
c1b0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
c1c0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
c1d0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
c1e0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
c1f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
c200: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
c210: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
c220: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
c230: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
c240: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
c250: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
c260: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
c270: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
c280: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
c290: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
c2a0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
c2b0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
c2c0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
c2d0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
c2e0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
c2f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
c300: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
c310: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
c320: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
c330: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
c340: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
c350: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c360: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
c370: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
c380: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
c390: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
c3a0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
c3b0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
c3c0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
c3d0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
c3e0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
c3f0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
c400: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
c410: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
c420: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
c430: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
c440: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
c450: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
c460: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
c470: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
c480: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
c490: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
c4a0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
c4b0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
c4c0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
c4d0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c4e0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
c4f0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
c500: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
c510: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
c520: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
c530: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
c540: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
c550: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
c560: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
c570: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
c580: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
c590: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
c5a0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
c5b0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
c5c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
c5d0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
c5e0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
c5f0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
c600: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
c610: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
c620: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
c630: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
c640: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
c650: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
c660: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
c670: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
c680: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
c690: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
c6a0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
c6b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
c6c0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
c6d0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
c6e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c6f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
c700: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
c710: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
c720: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
c730: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
c740: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
c750: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
c760: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
c770: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
c780: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
c790: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c7a0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
c7b0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
c7c0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
c7d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
c7e0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
c7f0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
c800: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
c810: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
c820: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
c830: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
c840: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
c850: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
c860: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
c870: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
c880: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
c890: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
c8a0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
c8b0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
c8c0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
c8d0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
c8e0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
c8f0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
c900: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
c910: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
c920: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
c930: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
c940: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
c950: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
c960: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
c970: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
c980: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
c990: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
c9a0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
c9b0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
c9c0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
c9d0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
c9e0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
c9f0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
ca00: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
ca10: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
ca20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
ca30: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
ca40: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
ca50: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
ca60: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
ca70: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
ca80: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
ca90: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
caa0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
cab0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
cac0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
cad0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
cae0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
caf0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
cb00: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
cb10: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
cb20: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
cb30: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
cb40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
cb50: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
cb60: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
cb70: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
cb80: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
cb90: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
cba0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
cbb0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
cbc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
cbd0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
cbe0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
cbf0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
cc00: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
cc10: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
cc20: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
cc30: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
cc40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
cc50: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
cc60: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
cc70: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
cc80: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
cc90: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
cca0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
ccb0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
ccc0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
ccd0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
cce0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
ccf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
cd00: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cd10: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
cd20: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cd30: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
cd40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cd50: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
cd60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cd70: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
cd80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
cd90: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
cda0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
cdb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
cdc0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
cdd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
cde0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
cdf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce00: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
ce10: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
ce20: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
ce30: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
ce40: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
ce50: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
ce60: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
ce70: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
ce80: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
ce90: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
cea0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
ceb0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
cec0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
ced0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
cee0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
cef0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
cf00: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
cf10: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
cf20: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
cf30: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
cf40: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
cf50: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
cf60: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
cf70: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
cf80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
cf90: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
cfa0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
cfb0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
cfc0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
cfd0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
cfe0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
cff0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
d000: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
d010: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
d020: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
d030: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
d040: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
d050: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
d060: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
d070: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
d090: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d0a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
d0b0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
d0c0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
d0d0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
d0e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d0f0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
d100: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
d110: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
d120: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
d130: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d140: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d150: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
d160: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
d170: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
d180: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
d190: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
d1a0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
d1b0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
d1c0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d1d0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
d1e0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
d1f0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
d200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
d210: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
d220: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
d230: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
d240: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
d250: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
d260: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
d270: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
d280: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
d290: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
d2a0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
d2b0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
d2c0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
d2d0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d2e0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
d2f0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
d300: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
d310: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
d320: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
d330: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
d340: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
d350: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
d360: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
d370: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
d380: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
d390: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
d3a0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
d3b0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
d3c0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
d3d0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
d3e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
d3f0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
d400: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
d410: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
d420: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
d430: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
d440: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
d450: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
d460: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
d470: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
d480: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
d490: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
d4a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d4b0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
d4c0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
d4d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
d4e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
d4f0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
d500: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
d510: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
d520: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
d530: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
d540: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
d550: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
d560: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
d570: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
d580: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
d590: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
d5a0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
d5b0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
d5c0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
d5d0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
d5e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d5f0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
d600: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
d610: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
d620: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
d630: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
d640: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
d650: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d660: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
d670: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
d680: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d690: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
d6a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
d6b0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
d6c0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
d6d0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
d6e0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
d6f0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
d700: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
d710: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
d720: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
d730: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
d740: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
d750: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
d760: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
d770: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
d780: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d790: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
d7a0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
d7b0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
d7c0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
d7d0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
d7e0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
d7f0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
d800: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
d810: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
d820: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
d830: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
d840: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
d850: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
d860: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
d870: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
d880: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
d890: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
d8a0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
d8b0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
d8c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
d8d0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
d8e0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
d8f0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
d900: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
d910: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
d920: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
d930: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
d940: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
d950: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
d960: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
d970: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
d980: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
d990: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
d9a0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
d9b0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
d9c0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
d9d0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
d9e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
d9f0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
da00: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
da10: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
da20: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
da30: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
da40: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
da50: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
da60: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
da70: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
da80: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
da90: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
daa0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
dab0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
dac0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
dad0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
dae0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
daf0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
db00: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
db10: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
db20: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
db30: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
db40: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
db50: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
db60: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
db70: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
db80: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
db90: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
dba0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
dbb0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
dbc0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
dbd0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
dbe0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
dbf0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
dc00: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
dc10: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
dc20: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
dc30: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
dc40: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
dc50: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
dc60: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
dc70: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
dc80: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
dc90: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
dca0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
dcb0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
dcc0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
dcd0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
dce0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
dcf0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
dd00: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
dd10: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
dd20: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
dd30: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
dd40: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
dd50: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
dd60: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
dd70: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
dd80: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
dd90: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
dda0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
ddb0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
ddc0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
ddd0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
dde0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
ddf0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
de00: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
de10: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
de20: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
de30: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
de40: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
de50: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
de60: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
de70: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
de80: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
de90: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
dea0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
deb0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
dec0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
ded0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
dee0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
def0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
df00: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
df10: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
df20: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
df30: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
df40: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
df50: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
df60: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
df70: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
df80: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
df90: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
dfa0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
dfb0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
dfc0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
dfd0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
dfe0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
dff0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e000: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
e010: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
e020: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
e030: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
e040: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
e050: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
e060: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
e070: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
e080: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
e090: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
e0a0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
e0b0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
e0c0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
e0d0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
e0e0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
e0f0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
e100: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
e110: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
e120: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
e130: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
e140: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
e150: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
e160: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
e170: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
e180: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
e190: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
e1a0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
e1b0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
e1c0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
e1d0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
e1e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e1f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e200: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
e210: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
e220: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
e230: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
e240: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
e250: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e260: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e270: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
e280: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
e290: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e2a0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e2b0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
e2c0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
e2d0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
e2e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e2f0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e300: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
e310: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
e320: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
e330: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e340: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
e350: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
e360: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e370: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e380: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
e390: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
e3a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
e3b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e3c0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
e3d0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
e3e0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e3f0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
e400: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
e410: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
e420: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
e430: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
e440: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
e450: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
e460: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
e470: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
e480: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
e490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
e4a0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
e4b0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
e4c0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
e4d0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e4e0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e4f0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
e500: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
e510: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
e520: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
e530: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
e540: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
e550: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
e560: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
e570: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
e580: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
e590: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e5a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e5b0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
e5c0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
e5d0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e5e0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
e5f0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
e600: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
e610: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
e620: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e630: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e640: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e650: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
e660: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
e670: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
e680: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e690: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e6a0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
e6b0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
e6c0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e6d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e6e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
e6f0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e700: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e710: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
e720: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
e730: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
e740: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
e750: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
e760: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
e770: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
e780: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
e790: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
e7a0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
e7b0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
e7c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
e7d0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
e7e0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
e7f0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
e800: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
e810: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
e820: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
e830: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
e840: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
e850: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
e860: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
e870: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
e880: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
e890: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e8a0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
e8b0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
e8c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
e8d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e8e0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
e8f0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e900: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
e910: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
e920: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
e930: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e940: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e950: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
e960: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
e970: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
e980: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
e990: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
e9a0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
e9b0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
e9c0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
e9d0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
e9e0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
e9f0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
ea00: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
ea10: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
ea20: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
ea30: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
ea40: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
ea50: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
ea60: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
ea70: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
ea80: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
ea90: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
eaa0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
eab0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
eac0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
ead0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
eae0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
eaf0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
eb00: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
eb10: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
eb20: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
eb30: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
eb40: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
eb50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
eb60: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
eb70: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
eb80: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
eb90: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
eba0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
ebb0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
ebc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
ebd0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
ebe0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
ebf0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ec00: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
ec10: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
ec20: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
ec30: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
ec40: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
ec50: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
ec60: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
ec70: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
ec80: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
ec90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
eca0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
ecb0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
ecc0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
ecd0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
ece0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
ecf0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
ed00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
ed10: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
ed20: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ed30: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ed40: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
ed50: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ed60: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ed70: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ed80: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
ed90: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eda0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
edb0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
edc0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
edd0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
ede0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
edf0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
ee00: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
ee10: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
ee20: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
ee30: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
ee40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
ee50: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
ee60: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
ee70: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
ee80: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
ee90: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
eea0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
eeb0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
eec0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
eed0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
eee0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
eef0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
ef00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
ef10: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ef20: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
ef30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
ef40: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
ef50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
ef60: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
ef70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ef80: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
ef90: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
efa0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
efb0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
efc0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
efd0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
efe0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
eff0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
f000: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
f010: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
f020: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
f030: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
f040: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
f050: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
f060: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
f070: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f080: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
f090: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
f0a0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
f0b0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
f0c0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
f0d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f0e0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
f0f0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
f100: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
f110: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
f120: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
f130: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
f140: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
f150: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
f160: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f170: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
f180: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
f190: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
f1a0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
f1b0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
f1c0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
f1d0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
f1e0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
f1f0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
f200: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
f210: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
f220: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
f230: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
f240: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
f250: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f260: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
f270: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
f280: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
f290: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
f2a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f2b0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
f2c0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
f2d0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
f2e0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
f2f0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
f300: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f310: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
f320: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
f330: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f340: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
f350: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
f360: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
f370: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
f380: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
f390: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
f3a0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
f3b0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
f3c0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f3d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f3e0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
f3f0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
f400: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
f410: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f420: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
f430: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
f440: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
f450: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
f460: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
f470: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f480: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
f490: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
f4a0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
f4b0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f4c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
f4d0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
f4e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
f4f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f500: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
f510: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
f520: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f530: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
f540: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f550: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
f560: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
f570: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
f580: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
f590: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
f5a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
f5b0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
f5c0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
f5d0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
f5e0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
f5f0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
f600: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
f610: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
f620: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
f630: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
f640: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
f650: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f660: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
f670: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
f680: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
f690: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
f6a0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
f6b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f6c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f6d0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
f6e0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f6f0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
f700: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
f710: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f720: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
f730: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
f740: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
f750: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
f760: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
f770: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
f780: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
f790: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
f7a0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
f7b0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
f7c0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
f7d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f7e0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
f7f0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
f800: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
f810: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
f820: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
f830: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
f840: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
f850: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
f860: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f870: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
f880: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
f890: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
f8a0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
f8b0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
f8c0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
f8d0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
f8e0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
f8f0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
f900: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
f910: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
f920: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
f930: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
f940: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
f950: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f960: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
f970: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
f980: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
f990: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
f9a0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
f9b0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
f9c0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
f9d0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
f9e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
f9f0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
fa00: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
fa10: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
fa20: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
fa30: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fa40: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
fa50: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
fa60: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
fa70: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
fa80: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
fa90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
faa0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
fab0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
fac0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
fad0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
fae0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
faf0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
fb00: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
fb10: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
fb20: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
fb30: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
fb40: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
fb50: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
fb60: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
fb70: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
fb80: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
fb90: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
fba0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
fbb0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
fbc0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
fbd0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
fbe0: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
fbf0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
fc00: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
fc10: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
fc20: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
fc30: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
fc40: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
fc50: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
fc60: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
fc70: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
fc80: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
fc90: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
fca0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
fcb0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
fcc0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
fcd0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fce0: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
fcf0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
fd00: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
fd10: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
fd20: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
fd30: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
fd40: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
fd50: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
fd60: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
fd70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
fd80: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
fd90: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
fda0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
fdb0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
fdc0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
fdd0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fde0: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
fdf0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fe00: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
fe10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
fe20: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
fe30: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
fe40: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
fe50: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
fe60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe70: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
fe80: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
fe90: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
fea0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
feb0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
fec0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
fed0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fee0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fef0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
ff00: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
ff10: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
ff20: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
ff30: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
ff40: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
ff50: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
ff60: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
ff70: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
ff80: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
ff90: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
ffa0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
ffb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
ffc0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
ffd0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
ffe0: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
fff0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10000 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10010 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
10020 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
10030 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10040 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10050 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
10060 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
10070 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
10080 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
10090 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
100a0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
100b0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
100c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
100d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
100e0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
100f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
10100 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
10110 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
10120 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
10130 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
10140 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10150 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
10160 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10170 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
10180 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
10190 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
101a0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
101b0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
101c0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
101d0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
101e0 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
101f0 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
10200 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
10210 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
10220 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
10230 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
10240 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
10250 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
10260 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
10270 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
10280 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
10290 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
102a0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
102b0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
102c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
102d0 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
102e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
102f0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10300 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
10310 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
10320 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
10330 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
10340 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
10350 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
10360 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
10370 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
10380 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10390 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
103a0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
103b0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
103c0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
103d0 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
103e0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
103f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
10400 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10410 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
10420 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
10430 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
10440 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
10450 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
10460 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
10470 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
10480 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
10490 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
104a0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
104b0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
104c0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
104d0 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
104e0 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
104f0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
10500 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
10510 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
10520 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10530 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
10540 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
10550 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10560 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
10570 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
10580 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
10590 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
105a0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
105b0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
105c0 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
105d0 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
105e0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
105f0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
10600 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
10610 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10620 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10630 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
10640 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
10650 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10660 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
10670 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
10680 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
10690 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
106a0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
106b0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
106c0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
106d0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
106e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
106f0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10700 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
10710 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
10720 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10740 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
10750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10760 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
10770 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10780 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10790 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
107a0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
107b0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
107c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
107d0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
107e0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
107f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10800 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10810 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
10820 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
10830 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10840 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10850 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10860 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10870 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10880 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
10890 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
108a0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
108b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
108c0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
108d0 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
108e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
108f0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10900 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10910 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10920 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
10930 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10940 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10950 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10960 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10970 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10980 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
10990 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
109a0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
109b0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
109c0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
109d0 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
109e0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
109f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
10a00 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10a10 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
10a20 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10a30 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
10a40 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
10a50 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
10a60 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
10a70 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
10a80 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
10a90 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
10aa0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
10ab0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
10ac0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
10ad0 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
10ae0 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
10af0 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
10b00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
10b10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
10b20 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10b30 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
10b40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
10b50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10b60 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
10b70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
10b80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
10b90 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
10ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10bb0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
10bc0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
10bd0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
10be0 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
10bf0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
10c00 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
10c10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10c20 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
10c30 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
10c40 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
10c50 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10c60 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10c70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
10c80 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
10c90 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
10ca0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
10cb0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
10cc0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
10cd0 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
10ce0 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
10cf0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
10d00 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
10d10 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
10d20 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
10d30 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
10d40 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10d50 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
10d60 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
10d70 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
10d80 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
10d90 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
10da0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
10db0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10dc0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
10dd0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
10de0 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
10df0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
10e00 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
10e10 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
10e20 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
10e30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
10e40 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
10e50 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
10e60 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
10e70 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
10e80 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
10e90 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
10ea0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
10eb0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
10ec0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
10ed0 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
10ee0 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
10ef0 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
10f00 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
10f10 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
10f20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
10f30 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
10f40 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
10f50 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
10f60 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
10f70 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
10f80 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
10f90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10fa0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
10fb0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
10fc0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
10fd0 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
10fe0 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
10ff0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11000 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
11010 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
11020 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
11030 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
11040 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
11050 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
11060 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
11070 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
11080 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
11090 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
110a0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
110b0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
110c0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
110d0 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
110e0 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
110f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
11100 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
11110 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
11120 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11140 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
11150 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
11160 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
11170 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11180 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
11190 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
111a0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
111b0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
111c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
111d0 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
111e0 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
111f0 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
11200 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
11210 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
11220 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
11230 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
11240 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
11250 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
11260 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11270 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
11280 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
11290 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
112a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
112b0 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
112c0 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
112d0 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
112e0 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
112f0 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
11300 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
11310 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
11320 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
11330 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
11340 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
11350 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
11360 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
11370 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
11380 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
11390 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
113a0 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
113b0 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
113c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
113d0 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
113e0 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
113f0 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
11400 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11410 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
11420 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
11430 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
11440 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
11450 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
11460 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
11470 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
11480 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
11490 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
114a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
114b0 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
114c0 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
114d0 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
114e0 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
114f0 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
11500 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
11510 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11520 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
11530 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
11540 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11550 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
11560 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11570 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
11580 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
11590 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
115a0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
115b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
115c0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
115d0 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
115e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
115f0 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
11600 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
11610 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
11620 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
11630 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
11640 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
11650 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
11660 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
11670 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11680 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
11690 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
116a0 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
116b0 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
116c0 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
116d0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
116e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
116f0 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
11700 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
11710 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11720 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
11730 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
11740 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
11750 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
11760 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
11770 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
11780 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
11790 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
117a0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
117b0 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
117c0 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
117d0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
117e0 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
117f0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11800 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
11810 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
11820 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
11830 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
11840 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
11850 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
11860 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
11870 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
11880 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
11890 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
118a0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
118b0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
118c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
118d0 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
118e0 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
118f0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
11900 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
11910 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
11920 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
11930 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
11940 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
11950 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
11960 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11970 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
11980 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
11990 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
119a0 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
119b0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
119c0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
119d0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
119e0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
119f0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
11a00 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
11a10 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
11a20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
11a30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
11a40 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
11a50 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
11a60 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
11a70 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
11a80 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
11a90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11aa0 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
11ab0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
11ac0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
11ad0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
11ae0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
11af0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11b00 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
11b10 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
11b20 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
11b30 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11b40 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
11b50 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
11b60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
11b70 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
11b80 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
11b90 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
11ba0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
11bb0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
11bc0 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
11bd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11be0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11bf0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11c00 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11c10 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11c20 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11c30 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11c40 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11c50 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11c60 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
11c70 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
11c80 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
11c90 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
11ca0 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
11cb0 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
11cc0 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
11cd0 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
11ce0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
11cf0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11d00 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11d10 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11d20 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11d30 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11d40 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11d50 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11d60 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
11d70 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
11d80 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
11d90 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
11da0 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
11db0 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
11dc0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11dd0 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
11de0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11df0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11e00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11e10 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
11e20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11e30 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11e50 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
11e60 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11e70 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
11e80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
11e90 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
11ea0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
11eb0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
11ec0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
11ed0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
11ee0 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
11ef0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11f00 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
11f10 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
11f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
11f30 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11f40 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
11f50 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
11f60 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
11f70 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
11f80 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
11f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11fa0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11fb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
11fc0 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
11fd0 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
11fe0 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
11ff0 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
12000 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
12010 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
12020 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
12030 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
12040 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
12050 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
12060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12070 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
12080 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
12090 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
120a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
120b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
120c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
120d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
120e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
120f0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12100 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
12110 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
12120 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
12130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12140 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
12150 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12160 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12170 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12180 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12190 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
121a0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
121b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
121c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
121d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
121e0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
121f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12200 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12210 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12220 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12230 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12240 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
12250 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
12260 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
12270 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
12280 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
12290 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
122a0 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
122b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
122c0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
122d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
122e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
122f0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
12300 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
12310 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
12320 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12330 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12340 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
12350 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
12360 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
12370 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
12380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12390 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
123a0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
123b0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
123c0 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
123d0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
123e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
123f0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
12400 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
12410 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
12420 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
12430 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12440 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
12450 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12460 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12470 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12480 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12490 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
124a0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
124b0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
124c0 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
124d0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
124e0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
124f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12500 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12510 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12520 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12530 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12540 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
12550 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12560 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12570 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12580 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
12590 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
125a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
125b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
125c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
125d0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
125e0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
125f0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12600 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12610 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
12620 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
12630 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
12640 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
12650 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12660 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
12670 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
12680 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
12690 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
126a0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
126b0 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
126c0 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
126d0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
126e0 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
126f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12700 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12710 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
12720 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
12730 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
12740 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
12750 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
12760 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
12770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12780 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
12790 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
127a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
127b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
127c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
127d0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
127e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
127f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12800 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
12810 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12820 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
12830 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
12840 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
12850 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
12860 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
12870 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
12880 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
12890 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
128a0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
128b0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
128c0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
128d0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
128e0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
128f0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
12900 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
12910 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
12920 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
12930 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12940 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
12950 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12960 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
12970 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12980 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
12990 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
129a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
129b0 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
129c0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
129d0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
129e0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
129f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12a00 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
12a10 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
12a20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12a30 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12a40 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
12a50 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
12a60 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
12a70 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
12a80 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
12a90 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12aa0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
12ab0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
12ac0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
12ad0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12ae0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
12af0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
12b00 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
12b10 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
12b20 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
12b30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12b40 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
12b50 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
12b60 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
12b70 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
12b80 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
12b90 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
12ba0 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
12bb0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
12bc0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
12bd0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
12be0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
12bf0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12c00 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
12c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12c20 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
12c30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12c40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12c50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12c60 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12c70 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
12c80 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
12c90 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12ca0 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
12cb0 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
12cc0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
12cd0 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
12ce0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
12cf0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
12d00 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
12d10 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
12d20 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
12d30 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
12d40 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
12d50 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
12d60 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
12d70 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
12d80 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
12d90 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
12da0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12db0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
12dc0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
12dd0 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
12de0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12df0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12e00 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12e10 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
12e20 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
12e30 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
12e40 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
12e50 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
12e60 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
12e70 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
12e80 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
12e90 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
12ea0 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
12eb0 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
12ec0 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
12ed0 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
12ee0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
12ef0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
12f00 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
12f10 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
12f20 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
12f30 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
12f40 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
12f50 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
12f60 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12f70 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
12f80 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
12f90 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
12fa0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12fb0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12fc0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
12fd0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12fe0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
12ff0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
13000 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
13010 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
13020 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13030 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
13040 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
13050 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
13060 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13070 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
13080 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
13090 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
130a0 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
130b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
130c0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
130d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
130e0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
130f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13100 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a  CACHE2 option..*
13110 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
13120 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
13130 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
13140 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
13150 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
13160 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
13170 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
13180 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
13190 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
131a0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
131b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
131c0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
131d0 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
131e0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
131f0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
13200 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
13210 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
13220 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
13230 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
13240 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
13250 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
13260 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
13270 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
13280 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
13290 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
132a0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
132b0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
132c0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
132d0 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
132e0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
132f0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
13300 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
13310 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
13320 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
13330 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
13340 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
13350 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
13360 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13370 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
13380 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
13390 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
133a0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
133b0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
133c0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
133d0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
133e0 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
133f0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13400 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
13410 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
13420 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
13430 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13440 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
13450 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
13460 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
13470 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
13480 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
13490 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
134a0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
134b0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
134c0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
134d0 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
134e0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
134f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13500 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
13510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13520 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13530 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
13540 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13550 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
13560 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13570 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
13580 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13590 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
135a0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
135b0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
135c0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
135d0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
135e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
135f0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
13600 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13610 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
13620 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
13630 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
13640 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13650 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
13660 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
13670 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
13680 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
13690 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
136a0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
136b0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
136c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
136d0 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
136e0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
136f0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13700 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
13710 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
13720 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
13730 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
13740 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
13750 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
13760 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
13770 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
13780 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
13790 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
137a0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
137b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
137c0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
137d0 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
137e0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
137f0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13800 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13810 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13820 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
13830 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
13840 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
13850 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13860 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
13870 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
13880 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
13890 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
138a0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
138b0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
138c0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
138d0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
138e0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
138f0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
13900 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
13910 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
13920 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
13930 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
13940 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
13950 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13960 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
13970 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
13980 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13990 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
139a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
139b0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
139c0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
139d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
139e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
139f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13a00 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
13a10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
13a20 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
13a30 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
13a40 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
13a50 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
13a60 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
13a70 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
13a80 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
13a90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
13aa0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
13ab0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
13ac0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13ad0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
13ae0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
13af0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
13b00 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
13b10 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13b20 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13b30 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13b40 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13b50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13b60 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
13b70 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
13b80 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
13b90 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
13ba0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
13bb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
13bc0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13bd0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
13be0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
13bf0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
13c00 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
13c10 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
13c20 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13c30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13c40 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
13c50 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
13c60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13c70 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13c80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13c90 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13ca0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
13cb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13cc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13cd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13ce0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
13cf0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13d00 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13d10 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13d20 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13d30 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
13d40 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
13d50 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
13d60 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
13d70 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
13d80 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
13d90 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
13da0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
13db0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
13dc0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
13dd0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
13de0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
13df0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
13e00 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13e10 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13e20 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13e30 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13e40 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13e50 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13e60 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
13e70 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
13e80 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
13e90 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
13ea0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
13eb0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13ec0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
13ed0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13ee0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13ef0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
13f00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
13f10 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
13f20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13f30 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
13f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13f50 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
13f60 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13f70 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13f80 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
13f90 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
13fa0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
13fb0 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
13fc0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
13fd0 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
13fe0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
13ff0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
14000 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14010 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
14020 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
14030 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
14040 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
14050 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
14060 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
14070 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
14080 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
14090 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
140a0 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
140b0 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
140c0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
140d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
140e0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
140f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
14100 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
14110 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
14120 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
14130 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14140 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
14150 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
14160 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14170 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14180 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14190 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
141a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
141b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
141c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
141d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
141e0 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
141f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14200 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
14210 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
14220 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
14230 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
14240 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
14250 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
14260 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14270 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
14280 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
14290 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
142a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
142b0 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
142c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
142d0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
142e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
142f0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14300 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
14310 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14320 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14330 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
14340 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
14350 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14360 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
14370 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
14380 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
14390 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
143a0 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
143b0 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
143c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
143d0 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
143e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
143f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
14400 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14410 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  LOG option is us
14420 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
14430 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c  the SQLite.** gl
14440 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d  obal [error log]
14450 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54  ..** (^The SQLIT
14460 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14470 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14480 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
14490 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
144a0 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
144b0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
144c0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
144d0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
144e0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
144f0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
14500 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
14510 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
14520 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
14530 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
14540 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
14550 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
14560 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
14570 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
14580 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
14590 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
145a0 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
145b0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
145c0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
145d0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
145e0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
145f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
14600 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
14610 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
14620 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
14630 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14640 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14650 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
14660 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
14670 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
14680 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14690 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
146a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
146b0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
146c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
146d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
146e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
146f0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
14700 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
14710 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
14720 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
14730 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
14740 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
14750 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
14760 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
14770 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
14780 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
14790 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
147a0 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
147b0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
147c0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
147d0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
147e0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
147f0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
14800 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
14810 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
14820 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
14830 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
14840 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
14850 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
14860 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
14870 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
14880 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
14890 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
148a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
148b0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
148c0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
148d0 3c 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f  <dd>^(This optio
148e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
148f0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14900 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65  e int. If non-ze
14910 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20  ro, then.** URI 
14920 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14930 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
14940 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
14950 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  s zero, then URI
14960 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20   handling.** is 
14970 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14980 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
14990 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
149a0 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  y enabled, all f
149b0 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73  ilenames.** pass
149c0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
149d0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
149e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71  _open_v2()], [sq
149f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
14a00 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
14a10 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
14a20 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
14a30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
14a40 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
14a50 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
14a60 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
14a70 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
14a80 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
14a90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
14aa0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
14ab0 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
14ac0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
14ad0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
14ae0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
14af0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
14b00 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
14b10 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
14b20 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
14b30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
14b40 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
14b50 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
14b60 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
14b70 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
14b80 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
14b90 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
14ba0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
14bb0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
14bc0 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
14bd0 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
14be0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
14bf0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14c00 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
14c10 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
14c20 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
14c30 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d>^This option t
14c40 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
14c50 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77  teger argument w
14c60 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
14c70 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c  ted as.** a bool
14c80 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
14c90 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
14ca0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
14cb0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
14cc0 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20  r.** full table 
14cd0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
14ce0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e  ry optimizer.  ^
14cf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
14d00 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
14d10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
14d20 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
14d30 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
14d40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14d50 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
14d60 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
14d70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
14d80 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
14d90 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
14da0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
14db0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
14dc0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
14dd0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
14de0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
14df0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
14e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
14e10 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
14e20 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
14e30 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
14e40 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
14e50 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
14e60 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
14e70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
14e80 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
14e90 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
14ea0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
14eb0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
14ec0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
14ed0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
14ee0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
14ef0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
14f00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14f10 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
14f20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14f30 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
14f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14f50 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
14f60 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
14f70 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
14f80 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
14f90 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
14fa0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
14fb0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
14fc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
14fd0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
14fe0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14ff0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15000 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
15010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15020 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
15030 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
15040 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15050 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15060 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15070 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
15080 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
15090 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
150a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
150b0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
150c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
150d0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
150e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
150f0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
15100 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
15110 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
15120 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
15130 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
15140 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15150 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15160 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
15170 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
15180 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
15190 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
151a0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
151b0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
151c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
151d0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
151e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
151f0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
15200 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15210 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15220 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15240 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15250 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15270 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15280 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
152a0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
152b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
152c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
152d0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
152e0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
152f0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
15300 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15310 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15320 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15330 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15340 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15350 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15360 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15370 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15380 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15390 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
153a0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
153b0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
153c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
153d0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
153e0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
153f0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
15400 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
15410 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15420 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15430 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15440 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15460 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15470 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
15480 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
15490 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
154a0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
154b0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
154c0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
154d0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
154e0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
154f0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
15500 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15510 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15520 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15530 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15540 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15550 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15560 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15580 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
15590 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
155a0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
155b0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
155c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
155d0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
155e0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
155f0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15600 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15610 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
15620 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20  d at run-time.  
15630 4e 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69  Nor may the maxi
15640 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
15650 20 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20   size.** exceed 
15660 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
15670 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
15680 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
15690 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
156a0 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
156b0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
156c0 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
156d0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
156e0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
156f0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
15700 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
15710 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
15720 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
15730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15740 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15750 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
15760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15770 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
15780 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  d>^This option i
15790 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
157a0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
157b0 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
157c0 77 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ws.** with the [
157d0 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
157e0 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
157f0 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15800 2e 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ..** SQLITE_CONF
15810 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15820 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74  E takes a 32-bit
15830 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
15840 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20  r value.** that 
15850 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61  specifies the ma
15860 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68  ximum size of th
15870 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a  e created heap..
15880 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
15890 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
158a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
158b0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
158c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
158d0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
158e0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
158f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15900 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
15910 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
15920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15930 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
15940 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
15950 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15960 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15970 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
15980 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
15990 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
159a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
159b0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
159c0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
159d0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
159e0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
159f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15a00 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
15a10 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
15a20 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
15a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15a40 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
15a50 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
15a60 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
15a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15a80 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
15a90 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
15aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
15ac0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
15ad0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15ae0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
15af0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15b00 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
15b10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
15b20 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
15b30 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
15b40 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
15b50 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
15b60 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
15b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15b80 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
15b90 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
15ba0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15bb0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
15bc0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
15bd0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15bf0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
15c00 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
15c10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15c20 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
15c30 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
15c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15c50 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
15c60 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
15c70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15c80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15c90 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
15ca0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15cb0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
15cc0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15cd0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
15ce0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15cf0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15d10 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15d20 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
15d30 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
15d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15d50 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
15d60 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
15d70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15d80 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15d90 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
15da0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
15db0 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
15dc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15dd0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15de0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
15df0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
15e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
15e10 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
15e20 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
15e30 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
15e40 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
15e50 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
15e60 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
15e70 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
15e80 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
15e90 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15ea0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
15eb0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15ec0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15ed0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
15ee0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15ef0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
15f00 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
15f10 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
15f20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
15f30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
15f40 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
15f50 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
15f60 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
15f70 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
15f80 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
15f90 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
15fa0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
15fb0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
15fc0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
15fd0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
15fe0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
15ff0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
16000 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
16010 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
16020 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
16030 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
16040 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
16050 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
16060 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
16070 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16080 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
16090 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
160a0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
160b0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
160c0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
160d0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
160e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
160f0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
16100 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
16110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
16120 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
16130 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
16140 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
16150 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16160 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
16170 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
16180 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
16190 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
161a0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
161b0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
161c0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
161d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
161e0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
161f0 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
16200 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
16210 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
16220 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
16230 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
16240 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
16250 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
16260 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
16270 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
16280 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
16290 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
162a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
162b0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
162c0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
162d0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
162e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
162f0 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
16300 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
16310 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
16320 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
16330 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
16340 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
16350 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
16360 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
16370 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
16380 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16390 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
163a0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
163b0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
163c0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
163d0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
163e0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
163f0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
16400 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
16410 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
16420 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
16430 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
16440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16450 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
16460 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
16470 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
16480 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
16490 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
164a0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
164b0 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
164c0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
164d0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
164e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
164f0 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
16500 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16510 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
16520 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
16530 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
16540 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
16550 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
16560 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
16570 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
16580 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
16590 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
165a0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
165b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
165c0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
165d0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
165e0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
165f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16600 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
16610 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
16620 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
16630 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
16640 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
16650 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
16660 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
16670 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16680 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
16690 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
166a0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
166b0 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
166c0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
166d0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
166e0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
166f0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16700 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
16710 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
16720 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
16730 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
16740 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
16750 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
16760 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
16770 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
16780 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
16790 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
167a0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
167b0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
167c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
167d0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
167e0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
167f0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
16800 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
16810 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
16820 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
16830 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16840 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16850 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
16860 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
16870 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
16880 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16890 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
168a0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
168b0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
168c0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
168d0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
168e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
168f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
16900 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
16910 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
16920 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16930 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
16940 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
16950 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
16960 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
16970 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16980 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
16990 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
169a0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
169b0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
169c0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
169d0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
169e0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
169f0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
16a00 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
16a10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16a20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
16a30 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
16a40 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
16a50 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
16a60 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
16a70 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
16a80 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
16a90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16aa0 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31  OOKASIDE       1
16ab0 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
16ac0 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16ad0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16ae0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
16af0 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e   1002  /* int in
16b00 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
16b10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16b20 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30  ABLE_TRIGGER  10
16b30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  03  /* int int* 
16b40 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
16b50 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
16b60 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
16b70 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
16b80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16b90 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
16ba0 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
16bb0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
16bc0 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
16bd0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
16be0 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
16bf0 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
16c00 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
16c10 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
16c20 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
16c30 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
16c40 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c  tibility..*/.SQL
16c50 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
16c60 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
16c70 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
16c80 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
16c90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16ca0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
16cb0 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
16cc0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
16cd0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
16ce0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
16cf0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
16d00 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
16d10 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
16d20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
16d30 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
16d40 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
16d50 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
16d60 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
16d70 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
16d80 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
16d90 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
16da0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
16db0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
16dc0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
16dd0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
16de0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
16df0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
16e00 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
16e10 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
16e20 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
16e30 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
16e40 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
16e50 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
16e60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16e70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16e80 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
16e90 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
16ea0 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
16eb0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
16ec0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
16ed0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
16ee0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
16ef0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
16f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
16f10 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
16f20 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
16f30 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
16f40 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
16f50 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
16f60 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
16f70 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
16f80 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
16f90 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
16fa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
16fb0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
16fc0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
16fd0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
16fe0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
16ff0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
17000 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
17010 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
17020 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
17030 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
17040 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
17050 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
17060 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
17070 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
17080 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
17090 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
170a0 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
170b0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
170c0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
170d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
170e0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
170f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
17100 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
17110 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
17120 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
17130 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17140 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
17150 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
17160 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
17170 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
17180 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
17190 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
171a0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
171b0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
171c0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
171d0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
171e0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
171f0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
17200 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
17210 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
17220 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
17230 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
17240 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
17250 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
17260 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17270 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
17280 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
17290 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
172a0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
172b0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
172c0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
172d0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
172e0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
172f0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
17300 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
17310 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
17320 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
17330 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
17340 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
17350 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
17360 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
17370 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
17380 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
17390 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
173a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
173b0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
173c0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
173d0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
173e0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
173f0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
17400 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
17410 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
17420 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
17430 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
17440 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
17450 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
17460 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
17470 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
17480 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
17490 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
174a0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
174b0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
174c0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
174d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
174e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
174f0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17500 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
17510 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
17520 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
17530 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
17540 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
17550 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17560 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
17570 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
17580 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
17590 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
175a0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
175b0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
175c0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
175d0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c   [rowid]..*/.SQL
175e0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
175f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
17600 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17610 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17620 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
17630 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
17640 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17650 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17660 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17670 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
17680 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
17690 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
176a0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
176b0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
176c0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
176d0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
176e0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
176f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17700 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
17710 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17720 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
17730 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
17740 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
17750 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
17760 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
17770 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
17780 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
17790 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
177a0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
177b0 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
177c0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
177d0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
177e0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
177f0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
17800 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
17810 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
17820 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
17830 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
17840 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
17850 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
17860 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
17870 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
17880 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
17890 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
178a0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
178b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
178c0 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
178d0 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
178e0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
178f0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
17900 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
17910 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
17920 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
17930 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
17940 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
17950 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
17960 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
17970 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
17980 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
17990 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
179a0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
179b0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
179c0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
179d0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
179e0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
179f0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
17a00 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
17a10 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
17a20 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
17a30 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
17a40 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
17a50 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
17a60 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
17a70 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
17a80 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
17a90 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
17aa0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
17ab0 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
17ac0 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
17ad0 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
17ae0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
17af0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
17b00 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
17b10 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
17b20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
17b30 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
17b40 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
17b50 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
17b60 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
17b70 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
17b80 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
17b90 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
17ba0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
17bb0 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
17bc0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
17bd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
17be0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
17bf0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
17c00 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
17c10 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
17c20 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
17c30 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17c40 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17c50 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
17c60 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
17c70 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
17c80 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17c90 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
17ca0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
17cb0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
17cc0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
17cd0 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
17ce0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
17cf0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
17d00 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17d10 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
17d20 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
17d30 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
17d40 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17d50 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
17d60 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
17d70 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
17d80 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
17d90 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
17da0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
17db0 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
17dc0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
17dd0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
17de0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
17df0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
17e00 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
17e10 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
17e20 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
17e30 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
17e40 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
17e50 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
17e60 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
17e70 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
17e80 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
17e90 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
17ea0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
17eb0 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
17ec0 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
17ed0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
17ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
17ef0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
17f00 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
17f10 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
17f20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
17f30 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
17f40 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17f50 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17f60 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17f70 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17f80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17f90 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17fa0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
17fb0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
17fc0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17fd0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
17fe0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
17ff0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
18000 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
18010 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
18020 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18030 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
18040 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
18050 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
18060 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
18070 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
18080 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
18090 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
180a0 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
180b0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
180c0 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
180d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
180e0 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
180f0 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
18100 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18110 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18120 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
18130 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
18140 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
18150 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
18160 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
18170 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
18180 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
18190 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
181a0 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
181b0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
181c0 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
181d0 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
181e0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
181f0 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
18200 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
18210 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
18220 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
18230 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
18240 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
18250 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
18260 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
18270 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
18280 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
18290 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
182a0 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
182b0 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
182c0 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
182d0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
182e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
182f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
18300 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
18310 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
18320 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
18330 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
18340 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
18350 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
18360 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
18370 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
18380 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
18390 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
183a0 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
183b0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
183c0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
183d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
183e0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
183f0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18400 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
18410 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18420 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18430 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18440 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18450 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18470 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
18480 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18490 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
184a0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
184b0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
184c0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
184d0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53  meaningful..*/.S
184e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
184f0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18500 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18520 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
18530 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
18540 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
18550 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
18560 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
18570 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
18580 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
18590 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
185a0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
185b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
185c0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
185d0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
185e0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
185f0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
18600 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
18610 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
18620 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
18630 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
18640 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
18650 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
18660 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
18670 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
18680 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
18690 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
186a0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
186b0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
186c0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
186d0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
186e0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
186f0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18700 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18710 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18720 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
18730 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
18740 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
18750 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18760 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
18770 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
18780 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
18790 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
187a0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
187b0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
187c0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
187d0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
187e0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
187f0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
18800 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
18810 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
18820 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
18830 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
18840 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
18850 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
18860 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
18870 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
18880 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
18890 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
188a0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
188b0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
188c0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
188d0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
188e0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
188f0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
18900 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
18910 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
18920 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
18930 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18940 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
18950 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
18960 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
18970 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
18980 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
18990 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
189a0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
189b0 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
189c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
189d0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
189e0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
189f0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18a00 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
18a10 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
18a20 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
18a30 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
18a40 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
18a50 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
18a60 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
18a70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18a80 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
18a90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18aa0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18ab0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
18ac0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
18ad0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
18ae0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
18af0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
18b00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18b10 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
18b20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18b30 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
18b40 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
18b50 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
18b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
18b70 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
18b80 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
18b90 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
18ba0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
18bb0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
18bc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18bd0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
18be0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18bf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
18c00 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
18c10 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
18c20 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
18c30 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
18c40 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
18c50 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
18c60 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e   void sqlite3_in
18c70 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
18c80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18c90 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
18ca0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
18cb0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
18cc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18cd0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
18ce0 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
18cf0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
18d00 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
18d10 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
18d20 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
18d30 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
18d40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
18d50 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
18d60 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
18d70 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
18d80 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
18d90 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
18da0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
18db0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
18dc0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
18dd0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
18de0 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
18df0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
18e00 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
18e10 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
18e20 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
18e30 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
18e40 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
18e50 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
18e60 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
18e70 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
18e80 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
18e90 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
18ea0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
18eb0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
18ec0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
18ed0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
18ee0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
18ef0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
18f00 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
18f10 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
18f20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
18f30 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
18f40 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
18f50 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
18f60 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
18f70 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
18f80 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
18f90 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
18fa0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
18fb0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
18fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
18fd0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
18fe0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
18ff0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
19000 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
19010 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
19020 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
19030 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
19040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
19050 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
19060 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
19070 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
19080 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
19090 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
190a0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
190b0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
190c0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
190d0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
190e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
190f0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
19100 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
19110 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
19120 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
19130 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
19140 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
19150 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
19160 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
19170 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
19180 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
19190 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
191a0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
191b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
191c0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
191d0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
191e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
191f0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
19200 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
19210 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
19230 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
19240 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
19250 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
19260 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
19270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
19280 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
19290 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
192a0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
192b0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
192c0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53  byte order..*/.S
192d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
192e0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
192f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
19300 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19310 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19320 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
19330 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
19340 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
19350 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
19360 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
19370 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
19380 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
19390 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
193a0 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
193b0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
193c0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
193d0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
193e0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
193f0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
19400 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
19410 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
19420 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
19430 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
19440 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
19450 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
19460 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19470 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
19480 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
19490 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
194a0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
194b0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
194c0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
194d0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
194e0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
194f0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
19500 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
19510 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19520 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
19530 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
19540 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
19550 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
19560 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
19570 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
19580 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
19590 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
195a0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
195b0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
195c0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
195d0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
195e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
195f0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
19600 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
19610 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
19620 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
19630 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
19640 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
19650 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
19660 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
19670 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
19680 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
19690 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
196a0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
196b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
196c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
196d0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
196e0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
196f0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
19700 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
19710 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
19720 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
19730 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
19740 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
19750 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
19760 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
19770 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
19780 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
19790 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
197a0 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
197b0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
197c0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
197d0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
197e0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
197f0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
19800 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
19810 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
19820 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
19830 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
19840 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
19850 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
19860 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
19870 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
19880 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
19890 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
198a0 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
198b0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
198c0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
198d0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
198e0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
198f0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
19900 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
19910 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
19920 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
19930 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
19940 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
19950 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
19960 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
19970 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
19980 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
19990 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
199a0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
199b0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
199c0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
199d0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
199e0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
199f0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
19a00 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
19a10 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
19a20 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
19a30 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
19a40 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
19a50 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
19a60 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
19a70 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
19a80 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
19a90 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
19aa0 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
19ab0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
19ac0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
19ad0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
19ae0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
19af0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
19b00 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
19b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
19b20 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
19b30 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
19b40 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19b50 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
19b60 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
19b70 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
19b80 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
19b90 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
19ba0 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
19bb0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
19bc0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
19bd0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
19be0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
19bf0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
19c00 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
19c10 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
19c20 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
19c30 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
19c40 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
19c50 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
19c60 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
19c70 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
19c80 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
19c90 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
19ca0 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
19cb0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
19cc0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
19cd0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
19ce0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
19cf0 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
19d00 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
19d10 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
19d20 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
19d30 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
19d40 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
19d50 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
19d60 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
19d70 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
19d80 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
19d90 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
19da0 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
19db0 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
19dc0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
19dd0 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
19de0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
19df0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
19e00 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
19e10 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
19e20 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
19e30 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
19e40 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
19e50 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
19e60 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
19e70 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
19e80 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
19e90 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
19ea0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
19eb0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
19ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
19ed0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
19ee0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
19ef0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
19f00 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
19f10 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
19f20 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
19f30 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
19f40 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
19f50 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
19f60 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
19f70 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
19f80 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
19f90 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
19fa0 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
19fb0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
19fc0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
19fd0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
19fe0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
19ff0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1a000 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1a010 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1a020 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1a030 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1a040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a050 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1a060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a070 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1a080 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a090 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1a0a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
1a0b0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
1a0c0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
1a0d0 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
1a0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a0f0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1a100 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
1a110 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1a120 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a130 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1a140 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1a150 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1a160 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1a170 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1a180 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1a190 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1a1a0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1a1b0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1a1c0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1a1d0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1a1e0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1a1f0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1a200 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1a210 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1a220 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1a230 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1a240 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1a250 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1a260 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1a270 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
1a280 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
1a290 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
1a2a0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1a2b0 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1a2c0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1a2d0 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1a2e0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1a2f0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1a300 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1a310 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1a320 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1a330 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1a340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a350 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
1a360 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1a370 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1a380 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1a390 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1a3a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a3b0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1a3c0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1a3d0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1a3e0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1a3f0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
1a400 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1a410 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1a420 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1a430 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1a440 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1a450 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1a460 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1a470 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1a480 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1a490 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1a4a0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1a4b0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a4c0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1a4d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1a4e0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1a4f0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1a500 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1a510 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1a520 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1a530 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1a540 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1a550 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1a560 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1a570 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1a580 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1a590 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1a5a0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1a5b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1a5c0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1a5d0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1a5e0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1a5f0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1a600 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1a610 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1a620 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1a630 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1a640 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1a650 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1a660 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1a670 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1a680 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1a690 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1a6a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a6b0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1a6c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1a6d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a6e0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1a6f0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1a700 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1a710 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1a720 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1a730 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1a740 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a750 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1a760 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1a770 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1a780 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1a790 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1a7a0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1a7b0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1a7c0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1a7d0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1a7e0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1a7f0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1a800 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1a810 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1a820 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1a830 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1a840 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1a850 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a860 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1a870 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1a880 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a890 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1a8a0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1a8b0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1a8c0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1a8d0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1a8e0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1a8f0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1a900 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1a910 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1a920 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1a930 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1a940 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1a950 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1a960 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1a970 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a980 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a990 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1a9a0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1a9b0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1a9c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a9d0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1a9e0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1a9f0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1aa00 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1aa10 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1aa20 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1aa30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1aa40 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1aa50 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1aa60 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1aa70 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1aa80 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1aa90 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1aaa0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1aab0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1aac0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1aad0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1aae0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1aaf0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1ab00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ab10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1ab20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ab30 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1ab40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ab50 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1ab60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ab70 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1ab80 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1ab90 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1aba0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1abb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1abc0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1abd0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1abe0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1abf0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ac00 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1ac10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ac20 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1ac30 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1ac40 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1ac50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1ac60 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1ac70 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1ac80 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1ac90 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1aca0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1acb0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1acc0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1acd0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1ace0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1acf0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1ad00 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1ad10 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1ad20 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1ad30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1ad40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ad50 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1ad60 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1ad70 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1ad80 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1ad90 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1ada0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1adb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1adc0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1add0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1ade0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1adf0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1ae00 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1ae10 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1ae20 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1ae30 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1ae40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1ae50 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1ae60 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1ae70 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1ae80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1ae90 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1aea0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1aeb0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1aec0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1aed0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1aee0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1aef0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1af00 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1af10 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1af20 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1af30 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1af40 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1af50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1af60 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1af70 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1af80 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1af90 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1afa0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1afb0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1afc0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1afd0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1afe0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1aff0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1b000 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1b010 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1b020 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1b030 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1b040 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1b050 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1b060 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1b070 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1b080 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1b090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1b0a0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  msg()]..*/.SQLIT
1b0b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1b0c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
1b0d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1b0e0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
1b0f0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
1b100 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1b110 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
1b120 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
1b130 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
1b140 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
1b150 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
1b160 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
1b170 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1b180 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
1b190 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1b1a0 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
1b1b0 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
1b1c0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
1b1d0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
1b1e0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
1b1f0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
1b200 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
1b210 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51  en here */.);.SQ
1b220 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1b230 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b240 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1b250 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b260 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1b270 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1b280 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1b290 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1b2a0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1b2b0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1b2c0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1b2d0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1b2e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1b2f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b300 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1b310 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1b320 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1b330 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1b340 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1b350 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1b360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b370 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1b380 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1b390 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1b3a0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1b3b0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1b3c0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1b3d0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1b3e0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1b3f0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1b400 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1b410 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1b420 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1b430 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1b440 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1b450 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1b460 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1b470 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1b480 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1b490 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1b4a0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1b4b0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1b4c0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1b4d0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1b4e0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1b4f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1b500 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1b510 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1b520 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1b530 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1b540 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1b550 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1b560 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1b570 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1b580 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1b590 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1b5a0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1b5b0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1b5c0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1b5d0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1b5e0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1b5f0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1b600 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1b610 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1b620 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1b630 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1b640 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1b650 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1b660 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1b670 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1b680 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1b690 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1b6a0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1b6b0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1b6c0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1b6d0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1b6e0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1b6f0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1b700 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b710 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1b720 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1b730 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1b740 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1b750 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1b760 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1b770 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1b780 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1b790 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1b7a0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1b7b0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1b7c0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1b7d0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1b7e0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1b7f0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1b800 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1b810 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1b820 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1b830 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1b840 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1b850 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1b860 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1b870 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1b880 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1b890 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1b8a0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1b8b0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1b8c0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1b8d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1b8e0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1b8f0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1b900 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1b910 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1b920 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1b930 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1b940 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1b950 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1b960 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1b970 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1b980 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1b990 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1b9a0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
1b9b0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1b9c0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1b9d0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1b9e0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1b9f0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1ba00 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1ba10 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1ba20 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1ba30 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1ba40 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1ba50 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1ba60 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1ba70 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1ba80 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1ba90 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1baa0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1bab0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1bac0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1bad0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1bae0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1baf0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1bb00 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1bb10 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1bb20 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1bb30 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1bb40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bb50 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1bb60 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1bb70 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1bb80 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1bb90 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1bba0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1bbb0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1bbc0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1bbd0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1bbe0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1bbf0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1bc00 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1bc10 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1bc20 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1bc30 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1bc40 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1bc50 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1bc60 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1bc70 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bc80 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1bc90 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1bca0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1bcb0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1bcc0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1bcd0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1bce0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1bcf0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1bd00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1bd10 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1bd20 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1bd30 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1bd40 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1bd50 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1bd60 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1bd70 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1bd80 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1bd90 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1bda0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1bdb0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1bdc0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1bdd0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1bde0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1bdf0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1be00 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1be10 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1be20 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1be30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1be40 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1be50 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1be60 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1be70 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1be80 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1be90 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1bea0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1beb0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1bec0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1bed0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1bee0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1bef0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1bf00 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1bf10 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1bf20 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1bf30 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1bf40 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1bf50 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1bf60 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1bf70 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1bf80 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1bf90 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1bfa0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1bfb0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1bfc0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1bfd0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1bfe0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1bff0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c000 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1c010 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1c020 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c030 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1c040 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1c050 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1c060 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1c070 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1c080 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c090 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c0a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1c0b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1c0c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1c0d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1c0e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1c0f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1c100 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1c110 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c120 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1c130 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1c140 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1c150 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1c160 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1c170 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1c180 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1c190 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1c1a0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1c1b0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1c1c0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1c1d0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c  string.)^.*/.SQL
1c1e0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1c1f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1c200 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1c210 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1c220 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1c230 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1c240 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f  a_list);.SQLITE_
1c250 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1c260 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1c270 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c280 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  , ...);.SQLITE_A
1c290 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1c2a0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1c2b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c2c0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1c2d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1c2e0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1c2f0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1c300 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1c310 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1c320 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1c330 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1c340 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1c350 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1c360 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1c370 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1c380 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1c390 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1c3a0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1c3b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1c3c0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1c3d0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1c3e0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1c3f0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1c400 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1c410 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1c420 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1c430 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c440 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1c450 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1c460 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1c470 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1c480 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1c490 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1c4a0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1c4b0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1c4c0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1c4d0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1c4e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c4f0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1c500 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1c510 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1c520 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1c530 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1c540 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1c550 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1c560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1c570 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1c580 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1c590 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1c5a0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1c5b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1c5c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c5d0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1c5e0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1c5f0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1c600 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1c610 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1c620 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1c630 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1c640 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1c650 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1c660 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1c670 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1c680 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1c690 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1c6a0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1c6b0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1c6c0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1c6d0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1c6e0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1c6f0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1c700 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1c710 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1c720 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c730 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1c740 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1c750 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1c760 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1c770 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1c780 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1c790 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1c7a0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1c7b0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1c7c0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1c7d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1c7e0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1c7f0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1c800 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1c810 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
1c820 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1c830 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1c840 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1c850 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
1c860 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
1c870 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
1c880 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1c890 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
1c8a0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
1c8b0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
1c8c0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
1c8d0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
1c8e0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c8f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c900 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1c910 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1c920 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1c930 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1c940 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c950 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
1c960 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1c970 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c980 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
1c990 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
1c9a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c9b0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
1c9c0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1c9d0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1c9e0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1c9f0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1ca00 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1ca10 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
1ca20 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
1ca30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ca40 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1ca50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ca60 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1ca70 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1ca80 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1ca90 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1caa0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1cab0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
1cac0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
1cad0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1cae0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1caf0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1cb00 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1cb10 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1cb20 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1cb30 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1cb40 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1cb50 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1cb60 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1cb70 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
1cb80 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1cb90 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1cba0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1cbb0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1cbc0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1cbd0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1cbe0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
1cbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1cc00 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1cc10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cc20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1cc30 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
1cc40 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1cc50 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1cc60 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1cc70 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1cc80 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1cc90 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1cca0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1ccb0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1ccc0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1ccd0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1cce0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1ccf0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1cd00 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1cd10 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1cd20 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1cd30 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1cd40 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1cd50 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1cd60 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1cd70 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1cd80 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1cd90 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1cda0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1cdb0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1cdc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1cdd0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1cde0 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1cdf0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1ce00 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1ce10 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1ce20 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1ce30 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1ce40 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1ce50 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1ce60 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1ce70 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1ce80 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1ce90 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1cea0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1ceb0 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1cec0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1ced0 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1cee0 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1cef0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1cf00 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1cf10 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1cf20 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1cf30 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1cf40 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1cf50 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1cf60 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1cf70 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1cf80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1cf90 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1cfa0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cfb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1cfc0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1cfd0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1cfe0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1cff0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1d000 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1d010 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1d020 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1d030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d040 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1d050 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1d060 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1d070 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1d080 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1d090 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1d0a0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1d0b0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1d0c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1d0d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1d0e0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1d0f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1d100 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1d110 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1d120 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45  loc(int);.SQLITE
1d130 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
1d140 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1d150 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
1d160 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1d170 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
1d180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1d190 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1d1a0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1d1b0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1d1c0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1d1d0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1d1e0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1d1f0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1d200 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1d210 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1d220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1d230 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1d240 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1d250 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1d260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d270 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1d280 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1d290 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1d2a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1d2b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1d2c0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1d2d0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1d2e0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1d2f0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1d300 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1d310 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d320 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1d330 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1d340 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1d350 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d360 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1d370 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1d380 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1d390 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1d3a0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1d3b0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d3c0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d3d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d3e0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1d3f0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1d400 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1d410 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1d420 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1d430 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1d440 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1d450 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1d460 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1d470 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1d480 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1d490 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1d4a0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1d4b0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1d4c0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1d4d0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1d4e0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1d4f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1d500 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1d510 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1d520 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1d530 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d540 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1d550 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1d560 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1d570 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d580 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1d590 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1d5a0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1d5b0 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  eset..*/.SQLITE_
1d5c0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1d5d0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1d5e0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1d5f0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1d600 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1d610 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1d620 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1d630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d640 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1d650 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1d660 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1d670 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1d680 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1d690 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1d6a0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1d6b0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1d6c0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1d6d0 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1d6e0 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1d6f0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1d700 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1d710 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1d720 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1d730 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1d740 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1d750 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1d760 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1d770 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1d780 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1d790 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1d7a0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1d7b0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1d7c0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1d7d0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1d7e0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d7f0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1d800 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1d810 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1d820 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  ** ^If N is less
1d830 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20   than one, then 
1d840 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  P can be a NULL 
1d850 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d860 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1d870 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1d880 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1d890 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1d8a0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1d8b0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74  less than one, t
1d8c0 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20  hen the PRNG is 
1d8d0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1d8e0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69  domness.** obtai
1d8f0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1d900 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1d910 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1d920 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1d930 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1d940 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1d950 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1d960 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1d970 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ore then.** the 
1d980 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1d990 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1d9a0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1d9b0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1d9c0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1d9d0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1d9e0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1d9f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1da00 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1da10 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1da20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1da30 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1da40 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1da50 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1da60 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1da70 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1da80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1da90 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1daa0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1dab0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1dac0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1dad0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1dae0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1daf0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1db00 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1db10 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1db20 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1db30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1db40 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1db50 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1db60 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1db70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1db80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1db90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1dba0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1dbb0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1dbc0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1dbd0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1dbe0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1dbf0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1dc00 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1dc10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1dc20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1dc30 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1dc40 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1dc50 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1dc60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1dc70 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1dc80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1dc90 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1dca0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1dcb0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1dcc0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1dcd0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1dce0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1dcf0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1dd00 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1dd10 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1dd20 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1dd30 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1dd40 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1dd50 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1dd60 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1dd70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1dd80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1dd90 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1dda0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1ddb0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1ddc0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1ddd0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1dde0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1ddf0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1de00 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1de10 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1de20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1de30 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1de40 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1de50 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1de60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1de70 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1de80 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1de90 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1dea0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1deb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1dec0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1ded0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1dee0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1def0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1df00 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1df10 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1df20 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1df30 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1df40 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1df50 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1df60 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1df70 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1df80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1df90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dfa0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1dfb0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1dfc0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1dfd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1dfe0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1dff0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1e000 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1e010 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1e020 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1e030 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1e040 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1e050 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1e060 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1e070 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1e080 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1e090 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1e0a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1e0b0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1e0c0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1e0d0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1e0e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1e0f0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1e100 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1e110 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1e120 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1e130 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1e140 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1e150 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1e160 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1e170 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1e180 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1e190 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1e1a0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1e1b0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1e1c0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1e1d0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1e1e0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1e1f0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1e200 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1e210 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1e220 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1e230 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1e240 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1e250 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1e260 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1e270 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1e280 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1e290 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1e2a0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1e2b0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1e2c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1e2d0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1e2e0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1e2f0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1e300 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1e310 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1e320 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1e330 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1e340 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1e350 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1e360 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1e370 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1e380 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1e390 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1e3a0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1e3b0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1e3c0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1e3d0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1e3e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1e3f0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1e400 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1e410 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1e420 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1e430 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1e440 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1e450 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1e460 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1e470 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1e480 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1e490 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1e4a0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1e4b0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1e4c0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1e4d0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1e4e0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1e4f0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1e500 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1e510 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1e520 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1e530 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1e540 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1e550 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1e560 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1e570 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1e580 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1e590 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1e5a0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1e5b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1e5c0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1e5d0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1e5e0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1e5f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1e600 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e610 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1e620 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1e630 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1e640 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1e650 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1e660 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1e670 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1e680 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1e690 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1e6a0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1e6b0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1e6c0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1e6d0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1e6e0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1e6f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1e700 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1e710 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1e720 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1e730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1e740 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1e750 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1e760 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1e770 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1e780 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1e790 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1e7a0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1e7b0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1e7c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1e7d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1e7e0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1e7f0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1e800 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e810 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1e820 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1e830 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1e840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e850 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1e860 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e870 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1e880 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1e890 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1e8a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e8b0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1e8c0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1e8d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1e8e0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1e8f0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1e900 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1e910 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1e920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1e930 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1e940 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1e950 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1e960 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1e970 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1e980 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1e990 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1e9a0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1e9b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e9c0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1e9d0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1e9e0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1e9f0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1ea00 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1ea10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1ea20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1ea30 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1ea40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ea50 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1ea60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1ea70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1ea80 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1ea90 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1eaa0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1eab0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1eac0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1ead0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1eae0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1eaf0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1eb00 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1eb10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1eb20 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1eb30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1eb40 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1eb50 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1eb60 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1eb70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1eb80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1eb90 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1eba0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1ebb0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1ebc0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1ebd0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ebe0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1ebf0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1ec00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1ec10 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1ec20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1ec30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1ec40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1ec50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ec60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1ec70 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1ec80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1ec90 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1eca0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1ecb0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1ecc0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1ecd0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1ece0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1ecf0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1ed00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ed10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ed20 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1ed30 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1ed40 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1ed50 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1ed60 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1ed70 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1ed80 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
1ed90 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
1eda0 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
1edb0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
1edc0 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
1edd0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
1ede0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1edf0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1ee00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1ee10 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1ee20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1ee30 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1ee40 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1ee50 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1ee60 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1ee70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ee80 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1ee90 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
1eea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1eeb0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
1eec0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
1eed0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1eee0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
1eef0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
1ef00 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
1ef10 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
1ef20 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
1ef30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1ef40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1ef50 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
1ef60 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1ef70 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
1ef80 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
1ef90 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
1efa0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
1efb0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
1efc0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1efd0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
1efe0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
1eff0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
1f000 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
1f010 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
1f020 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
1f030 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1f040 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1f050 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1f060 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
1f070 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f080 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
1f090 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
1f0a0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
1f0b0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
1f0c0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
1f0d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f0e0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
1f0f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1f100 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1f110 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1f120 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1f130 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1f140 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1f150 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
1f160 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
1f170 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1f180 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
1f190 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1f1a0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
1f1b0 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
1f1c0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
1f1d0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
1f1e0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1f1f0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1f200 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1f210 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
1f220 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1f230 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1f240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f260 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1f270 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1f280 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1f290 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1f2a0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1f2b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f2c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f2d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f2e0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1f2f0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1f300 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f310 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f330 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1f340 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1f350 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f360 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f370 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f380 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1f390 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1f3a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f3b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f3c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f3d0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1f3e0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1f3f0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f400 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f410 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f420 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1f430 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1f440 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f450 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f470 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1f480 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1f490 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f4a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f4c0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1f4d0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1f4e0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f4f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f500 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1f510 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1f520 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1f530 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f540 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f550 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f560 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1f570 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1f580 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f590 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f5a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f5b0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1f5c0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1f5d0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f5e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f5f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f600 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1f610 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1f620 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1f630 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f640 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f650 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1f660 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f670 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f680 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f690 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1f6a0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1f6b0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f6c0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f6d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f6e0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1f6f0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1f700 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f710 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f720 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f730 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1f740 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1f750 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1f760 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f770 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f780 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1f790 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1f7a0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1f7b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f7c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f7d0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1f7e0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1f7f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f800 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f810 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f820 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1f830 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1f840 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1f850 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1f860 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f870 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1f880 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1f890 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1f8a0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1f8b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f8c0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1f8d0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1f8e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1f8f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1f910 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1f920 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
1f930 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
1f940 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f950 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1f960 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1f970 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1f980 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1f990 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1f9a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1f9b0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1f9c0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1f9d0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1f9e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f9f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1fa00 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1fa10 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1fa20 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1fa30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fa40 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1fa50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1fa60 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1fa70 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1fa80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fa90 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1faa0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1fab0 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1fac0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1fad0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fae0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1faf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1fb00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fb10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fb20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fb30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1fb40 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1fb50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1fb60 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1fb70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fb80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1fb90 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1fba0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1fbb0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1fbc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fbd0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1fbe0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1fbf0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1fc00 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1fc10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fc20 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1fc30 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1fc40 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1fc50 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1fc60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fc70 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1fc80 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1fc90 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1fca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fcb0 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
1fcc0 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
1fcd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1fce0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fcf0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1fd00 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1fd10 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1fd20 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1fd30 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1fd40 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1fd50 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1fd60 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1fd70 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1fd80 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1fd90 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1fda0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1fdb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1fdc0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1fdd0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1fde0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1fdf0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1fe00 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1fe10 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1fe20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1fe30 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1fe40 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1fe50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1fe60 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1fe70 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1fe80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1fe90 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1fea0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1feb0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1fec0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1fed0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1fee0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1fef0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1ff00 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1ff10 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1ff20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1ff30 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1ff40 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1ff50 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1ff60 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1ff70 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1ff80 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
1ff90 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
1ffa0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1ffb0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1ffc0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
1ffd0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
1ffe0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
1fff0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20000 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20010 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
20020 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20030 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20040 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
20050 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
20060 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
20070 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
20080 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20090 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
200a0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
200b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
200c0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
200d0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
200e0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
200f0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
20100 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
20110 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20120 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
20130 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
20140 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
20150 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
20160 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
20170 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
20180 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
20190 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
201a0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
201b0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
201c0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
201d0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
201e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
201f0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
20200 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
20210 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
20220 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
20230 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
20240 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
20250 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
20260 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
20270 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
20280 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
20290 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
202a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
202b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
202c0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
202d0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
202e0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
202f0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
20300 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
20310 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
20320 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
20330 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
20340 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
20350 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
20360 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
20370 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
20380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20390 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
203a0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
203b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
203c0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
203d0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
203e0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
203f0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
20400 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
20410 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
20420 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
20430 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
20440 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
20450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20460 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
20470 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
20480 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
20490 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
204a0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
204b0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
204c0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
204d0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
204e0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
204f0 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
20500 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
20510 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
20520 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
20530 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
20540 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
20550 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
20560 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
20570 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
20580 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
20590 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
205a0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
205b0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
205c0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
205d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
205e0 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
205f0 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
20600 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
20610 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
20620 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
20630 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
20640 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
20650 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
20660 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
20670 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
20680 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
20690 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
206a0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
206b0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
206c0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
206d0 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
206e0 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
206f0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
20700 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
20710 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
20720 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
20730 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
20740 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
20750 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
20760 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
20770 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
20780 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
20790 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
207a0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
207b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
207c0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
207d0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
207e0 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
207f0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
20800 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
20810 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
20820 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
20830 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
20840 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
20850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20860 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
20870 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20880 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
20890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
208a0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
208b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
208c0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
208d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
208e0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
208f0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
20900 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
20910 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49  raph..**.*/.SQLI
20920 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
20930 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
20940 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
20950 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
20960 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
20970 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
20980 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
20990 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
209a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
209b0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
209c0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
209d0 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
209e0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
209f0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
20a00 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20a10 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
20a20 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
20a30 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20a40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
20a50 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
20a60 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
20a70 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
20a80 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
20a90 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
20aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20ab0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
20ac0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
20ad0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
20ae0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
20af0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
20b00 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
20b10 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
20b20 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
20b30 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
20b40 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
20b50 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
20b60 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
20b70 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
20b80 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
20b90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
20ba0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
20bb0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
20bc0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
20bd0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
20be0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
20bf0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
20c00 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
20c10 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
20c20 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
20c30 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
20c40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
20c50 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
20c60 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
20c70 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
20c80 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
20c90 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
20ca0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
20cb0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
20cc0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
20cd0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
20ce0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
20cf0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
20d00 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
20d10 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
20d20 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
20d30 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
20d40 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
20d50 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
20d60 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
20d70 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
20d80 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
20d90 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
20da0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
20db0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
20dc0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
20dd0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
20de0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
20df0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
20e00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20e10 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
20e20 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
20e30 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
20e40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
20e50 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
20e60 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
20e70 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
20e80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20e90 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
20ea0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
20eb0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
20ec0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
20ed0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
20ee0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
20ef0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
20f00 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
20f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f20 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
20f30 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
20f40 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
20f50 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
20f60 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
20f70 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
20f80 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
20f90 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
20fa0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20fb0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
20fc0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
20fd0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
20fe0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
20ff0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
21000 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
21010 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
21020 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
21030 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
21040 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21050 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
21060 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
21070 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
21080 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
21090 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
210a0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
210b0 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
210c0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
210d0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
210e0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
210f0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
21100 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21110 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21120 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
21130 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
21140 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
21150 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
21160 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
21170 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
21180 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
21190 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
211a0 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
211b0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
211c0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
211d0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
211e0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
211f0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21200 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
21210 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
21220 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
21230 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21240 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21250 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
21260 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
21270 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
21280 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
21290 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
212a0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
212b0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
212c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
212d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
212e0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
212f0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
21300 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
21310 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21320 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
21330 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
21340 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
21350 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
21360 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
21370 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
21380 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
21390 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
213a0 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
213b0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
213c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
213d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
213e0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
213f0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
21400 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21410 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
21420 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
21430 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
21440 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
21450 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
21460 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
21470 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
21480 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
21490 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
214a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
214b0 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
214c0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
214d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
214e0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
214f0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
21500 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21510 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
21520 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
21530 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
21540 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
21550 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
21560 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
21570 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21580 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
21590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
215a0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
215b0 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
215c0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
215d0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
215e0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
215f0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
21600 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
21610 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
21620 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
21630 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
21640 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
21650 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
21660 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
21670 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
21680 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
21690 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
216a0 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
216b0 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
216c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
216d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
216e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
216f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21700 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
21710 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
21720 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
21730 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
21740 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
21750 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
21760 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
21770 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
21780 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21790 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
217a0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
217b0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
217c0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
217d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
217e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
217f0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
21800 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
21810 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
21820 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
21830 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
21840 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
21850 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
21860 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
21870 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
21880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21890 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
218a0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
218b0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
218c0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
218d0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
218e0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
218f0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
21900 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
21910 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
21920 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
21930 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
21940 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
21950 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
21960 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
21970 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
21980 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
21990 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
219a0 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
219b0 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
219c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
219d0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
219e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
219f0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
21a00 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
21a10 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
21a20 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
21a30 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
21a40 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
21a50 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
21a60 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
21a70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21a80 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
21a90 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
21aa0 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
21ab0 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
21ac0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
21ad0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
21ae0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
21af0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
21b00 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
21b10 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
21b20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
21b30 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
21b40 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
21b50 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
21b60 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
21b70 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21b80 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
21b90 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
21ba0 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
21bb0 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
21bc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
21bd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
21be0 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
21bf0 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
21c00 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
21c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
21c20 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
21c30 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
21c40 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
21c50 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
21c60 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
21c70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
21c80 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
21c90 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
21ca0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
21cb0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
21cc0 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
21cd0 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
21ce0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
21cf0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
21d00 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
21d10 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
21d20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
21d30 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
21d40 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
21d50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
21d60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
21d70 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
21d80 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
21d90 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
21da0 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
21db0 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
21dc0 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
21dd0 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
21de0 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
21df0 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
21e00 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
21e10 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
21e20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
21e30 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
21e40 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
21e50 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
21e60 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
21e70 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
21e80 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
21e90 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
21ea0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
21eb0 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
21ec0 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
21ed0 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
21ee0 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
21ef0 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
21f00 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
21f10 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
21f20 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
21f30 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
21f40 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
21f50 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
21f60 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
21f70 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
21f80 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
21f90 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
21fa0 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
21fb0 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
21fc0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
21fd0 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
21fe0 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
21ff0 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
22000 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f  ive path. .** ^O
22010 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
22020 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
22030 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
22040 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
22050 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
22060 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a  (e.g. "C:")..**.
22070 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
22080 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
22090 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
220a0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
220b0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
220c0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
220d0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
220e0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
220f0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
22100 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
22110 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
22120 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  n]..** SQLite in
22130 74 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c  terprets the fol
22140 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65  lowing three que
22150 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
22160 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
22170 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
22180 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
22190 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
221a0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
221b0 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
221c0 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
221d0 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
221e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
221f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
22200 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
22210 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
22220 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22230 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
22240 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
22250 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
22260 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
22270 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
22280 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
22290 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
222a0 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
222b0 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
222c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
222d0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
222e0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
222f0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
22300 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
22310 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
22320 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
22330 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
22340 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
22350 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
22360 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
22370 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
22380 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
22390 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
223a0 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
223b0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
223c0 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
223d0 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
223e0 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
223f0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
22400 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
22410 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
22420 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
22430 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
22440 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
22450 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22460 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
22470 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
22480 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
22490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
224a0 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
224b0 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
224c0 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
224d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
224e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
224f0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
22500 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
22510 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
22520 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
22530 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
22540 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
22550 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
22560 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
22570 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
22580 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
22590 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
225a0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
225b0 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
225c0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
225d0 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
225e0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
225f0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
22600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
22610 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
22620 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
22630 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
22640 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
22650 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
22660 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
22670 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
22680 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
22690 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
226a0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
226b0 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
226c0 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
226d0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
226e0 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
226f0 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
22700 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
22710 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
22720 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
22730 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
22740 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
22750 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
22760 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
22770 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
22780 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
22790 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
227a0 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
227b0 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
227c0 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
227d0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
227e0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
227f0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22800 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
22810 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
22820 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
22830 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22840 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
22850 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
22860 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
22870 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
22880 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
22890 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
228a0 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
228b0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
228c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
228d0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
228e0 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
228f0 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
22900 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
22910 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
22920 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
22930 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
22940 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
22950 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
22960 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
22970 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22980 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
22990 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
229a0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
229b0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
229c0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
229d0 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
229e0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
229f0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22a00 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22a10 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
22a20 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
22a30 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
22a40 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
22a50 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
22a60 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
22a70 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
22a80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
22a90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
22aa0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22ab0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
22ac0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
22ad0 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
22ae0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
22af0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
22b00 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
22b10 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
22b20 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
22b30 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
22b40 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
22b50 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
22b60 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
22b70 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
22b80 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
22b90 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
22ba0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
22bb0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
22bc0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
22bd0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
22be0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
22bf0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
22c00 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
22c10 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
22c20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
22c30 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
22c40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
22c50 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22c60 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
22c70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22c80 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22c90 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
22ca0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
22cb0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
22cc0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
22cd0 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
22ce0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
22cf0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
22d00 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
22d10 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
22d20 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
22d30 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
22d40 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
22d50 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
22d60 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
22d70 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
22d80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
22d90 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
22da0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
22db0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
22dc0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
22dd0 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
22de0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
22df0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
22e00 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
22e10 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
22e20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
22e30 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
22e40 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
22e50 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
22e60 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22e70 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
22e80 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
22e90 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
22ea0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
22eb0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
22ec0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
22ed0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
22ee0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
22ef0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
22f00 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
22f10 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
22f20 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22f30 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
22f40 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
22f50 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
22f60 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
22f70 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
22f80 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
22f90 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
22fa0 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
22fb0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
22fc0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
22fd0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22fe0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
22ff0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
23000 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
23010 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
23020 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
23030 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
23040 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
23050 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
23060 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
23070 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
23080 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
23090 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
230a0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
230b0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
230c0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
230d0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
230e0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
230f0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
23100 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
23110 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
23120 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
23130 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
23140 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
23150 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
23160 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
23170 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
23180 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
23190 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
231a0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
231b0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
231c0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
231d0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
231e0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
231f0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
23200 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
23210 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
23220 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
23230 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
23240 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
23250 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
23260 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
23270 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
23280 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
23290 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
232a0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
232b0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
232c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
232d0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
232e0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
232f0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
23300 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
23310 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
23320 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
23330 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
23340 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
23350 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
23360 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
23370 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
23380 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
23390 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
233a0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
233b0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
233c0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
233d0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
233e0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
233f0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
23400 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
23410 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
23420 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
23430 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
23440 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
23450 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
23460 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
23470 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
23480 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
23490 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
234a0 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
234b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
234c0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
234d0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
234e0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
234f0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
23500 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
23510 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
23520 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
23530 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
23540 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
23550 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
23560 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
23570 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
23580 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
23590 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
235a0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
235b0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
235c0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
235d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
235e0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
235f0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
23600 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
23610 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
23620 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
23630 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
23640 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
23650 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
23660 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
23670 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
23680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
23690 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
236a0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
236b0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
236c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
236d0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
236e0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
236f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
23700 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
23710 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
23720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
23730 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
23740 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
23750 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
23760 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
23770 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
23780 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
23790 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
237a0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
237b0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
237c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
237d0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
237e0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
237f0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
23800 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
23810 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
23820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
23830 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
23840 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
23850 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
23860 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
23870 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
23880 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
23890 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
238a0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
238b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
238c0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
238d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
238e0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
238f0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
23900 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
23910 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
23920 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
23930 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
23940 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
23950 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
23960 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
23970 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
23980 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
23990 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
239a0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
239b0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
239c0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
239d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
239e0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
239f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23a00 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23a10 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
23a20 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
23a30 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
23a40 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
23a50 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
23a60 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
23a70 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
23a80 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
23a90 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
23aa0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
23ab0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
23ac0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
23ad0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
23ae0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
23af0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
23b00 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
23b10 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
23b20 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
23b30 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
23b40 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
23b50 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23b60 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
23b70 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
23b80 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
23b90 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
23ba0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
23bb0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
23bc0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
23bd0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
23be0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
23bf0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
23c00 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
23c10 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
23c20 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
23c30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
23c40 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
23c50 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
23c60 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
23c70 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23c80 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
23c90 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
23ca0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
23cb0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
23cc0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
23cd0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
23ce0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
23cf0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
23d00 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
23d10 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
23d20 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
23d30 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
23d40 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
23d50 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
23d60 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
23d70 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
23d80 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
23d90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
23da0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
23db0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
23dc0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
23dd0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
23de0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
23df0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
23e00 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
23e10 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
23e20 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
23e30 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
23e40 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
23e50 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
23e60 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
23e70 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
23e80 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
23e90 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
23ea0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
23eb0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
23ec0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
23ed0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
23ee0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
23ef0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
23f00 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
23f10 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
23f20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23f30 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23f40 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
23f50 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
23f60 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
23f70 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
23f80 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
23f90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
23fa0 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
23fb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
23fc0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
23fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
23fe0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
23ff0 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
24000 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
24010 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
24020 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
24030 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
24040 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
24050 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
24060 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
24070 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
24080 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
24090 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
240a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
240b0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
240c0 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
240d0 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
240e0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
240f0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
24100 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24110 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
24120 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
24130 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
24140 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
24150 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
24160 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
24170 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
24180 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
24190 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
241a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
241b0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
241c0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
241d0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
241e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
241f0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
24200 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
24210 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
24220 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
24230 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
24240 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
24250 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
24260 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
24270 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
24280 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
24290 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
242a0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
242b0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
242c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
242d0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
242e0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
242f0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
24300 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
24310 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
24320 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
24330 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
24340 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
24350 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
24360 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
24370 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
24380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
24390 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
243a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
243b0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
243c0 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
243d0 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
243e0 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
243f0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
24400 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
24410 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
24420 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
24430 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
24440 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
24450 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24460 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
24470 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
24480 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
24490 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
244a0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
244b0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
244c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
244d0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
244e0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
244f0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
24500 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
24510 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
24520 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
24530 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
24540 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
24550 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
24560 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
24570 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
24580 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
24590 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
245a0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
245b0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
245c0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
245d0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
245e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
245f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
24600 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
24610 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
24620 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
24630 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
24640 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
24650 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
24660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
24670 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
24680 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
24690 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
246a0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
246b0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
246c0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
246d0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
246e0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
246f0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
24700 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
24710 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
24720 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
24730 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
24740 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
24750 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
24760 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
24770 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
24780 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53  not be set..*/.S
24790 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
247a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
247b0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
247c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
247d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
247e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
247f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
24800 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24810 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
24820 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
24830 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24840 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
24850 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
24860 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
24870 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
24880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24890 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
248a0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
248b0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
248c0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
248d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
248e0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
248f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
24900 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
24910 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
24920 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
24930 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
24940 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
24950 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
24960 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
24970 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
24980 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
24990 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
249a0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
249b0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
249c0 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
249d0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
249e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
249f0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
24a00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24a10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24a20 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
24a30 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
24a40 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
24a50 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
24a60 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
24a70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
24a80 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
24a90 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
24aa0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
24ab0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24ac0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
24ad0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24ae0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
24af0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
24b00 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
24b10 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
24b20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
24b30 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
24b40 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24b50 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
24b60 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24b70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
24b80 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
24b90 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
24ba0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
24bb0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24bc0 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
24bd0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24be0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
24bf0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
24c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
24c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24c20 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
24c30 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
24c40 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24c50 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
24c60 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24c70 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
24c80 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
24c90 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
24ca0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
24cb0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24cc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24cd0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
24ce0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
24cf0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
24d00 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
24d10 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
24d20 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
24d30 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
24d40 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24d50 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24d60 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
24d70 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24d80 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
24d90 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
24da0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
24db0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
24dc0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
24dd0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
24de0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
24df0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
24e00 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
24e10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
24e20 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
24e30 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
24e40 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
24e50 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
24e60 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
24e70 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
24e80 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
24e90 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
24ea0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
24eb0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
24ec0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
24ed0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
24ee0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
24ef0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
24f00 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
24f10 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
24f20 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
24f30 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
24f40 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
24f50 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
24f60 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
24f70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
24f80 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
24f90 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
24fa0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
24fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24fc0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
24fd0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
24fe0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
24ff0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
25000 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
25010 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
25020 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
25030 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
25040 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
25050 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
25060 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
25070 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
25080 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
25090 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
250a0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
250b0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
250c0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
250d0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
250e0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
250f0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
25100 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
25110 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
25120 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
25130 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
25140 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
25150 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
25160 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
25170 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
25180 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
25190 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
251a0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
251b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
251c0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
251d0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
251e0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
251f0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
25200 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
25210 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
25220 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
25230 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
25240 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
25250 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
25260 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
25270 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
25280 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
25290 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
252a0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
252b0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
252c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
252d0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
252e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
252f0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
25300 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
25310 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
25320 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
25330 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
25340 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
25350 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
25360 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
25370 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
25380 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
25390 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
253a0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
253b0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
253c0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
253d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
253e0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
253f0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
25400 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
25410 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
25420 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
25430 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25440 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
25450 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
25460 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
25470 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
25480 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
25490 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
254a0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
254b0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
254c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
254d0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
254e0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
254f0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
25500 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
25510 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
25520 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
25530 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
25540 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
25550 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
25560 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
25570 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25580 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
25590 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
255a0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
255b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
255c0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
255d0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
255e0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
255f0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
25600 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25610 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
25620 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25630 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25640 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
25650 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
25660 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
25670 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
25680 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25690 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
256a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
256b0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
256c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
256d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
256e0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
256f0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
25700 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
25710 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
25720 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25730 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
25740 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
25750 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
25760 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
25770 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25780 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
25790 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
257a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
257b0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
257c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
257d0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
257e0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
257f0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
25800 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25810 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
25820 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
25830 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25840 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
25850 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25860 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
25870 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
25880 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
25890 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
258a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
258b0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
258c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
258d0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
258e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
258f0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
25900 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
25910 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
25920 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
25930 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
25940 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
25950 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
25960 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
25970 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
25980 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
25990 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
259a0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
259b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
259c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
259d0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
259e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
259f0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
25a00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25a10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
25a20 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
25a30 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
25a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25a50 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
25a60 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25a70 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
25a80 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25a90 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
25aa0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
25ab0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
25ac0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
25ad0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
25ae0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
25af0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25b00 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25b10 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25b20 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
25b30 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
25b40 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
25b50 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
25b60 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
25b70 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
25b80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25b90 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
25ba0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
25bb0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
25bc0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
25bd0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25be0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
25bf0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
25c00 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
25c10 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
25c20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
25c30 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
25c40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
25c50 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
25c60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25c70 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
25c80 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
25c90 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
25ca0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
25cb0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
25cc0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
25cd0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
25ce0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
25cf0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
25d00 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
25d10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25d20 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
25d30 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
25d40 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25d50 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
25d60 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
25d70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25d80 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
25d90 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
25da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25db0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
25dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
25dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25de0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
25e00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25e10 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
25e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
25e30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25e40 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25e50 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
25e60 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
25e70 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25e80 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
25e90 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
25ea0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25eb0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
25ec0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
25ed0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
25ee0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
25ef0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
25f00 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
25f10 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
25f20 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
25f30 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
25f40 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
25f50 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
25f60 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
25f70 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
25f80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
25f90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
25fa0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
25fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25fc0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
25fd0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
25fe0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
25ff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
26000 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
26010 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
26020 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
26030 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
26040 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
26050 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
26060 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
26070 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
26080 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
26090 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
260a0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
260b0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
260c0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
260d0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
260e0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
260f0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
26100 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
26110 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
26120 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
26130 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
26140 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
26150 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
26160 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
26170 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
26180 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
26190 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
261a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
261b0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
261c0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
261d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
261e0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
261f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
26200 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
26210 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
26220 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
26230 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
26240 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
26250 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
26260 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
26270 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
26280 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
26290 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
262a0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
262b0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
262c0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
262d0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
262e0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
262f0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
26300 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
26310 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
26320 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
26330 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
26340 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
26350 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
26360 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
26370 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
26380 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
26390 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
263a0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
263b0 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
263c0 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
263d0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
263e0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
263f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
26400 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
26410 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
26420 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
26430 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
26440 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
26450 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
26460 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
26470 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
26480 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
26490 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
264a0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
264b0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
264c0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
264d0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
264e0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
264f0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
26500 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
26510 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
26520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26530 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
26540 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
26550 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
26560 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
26570 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
26580 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
26590 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
265a0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
265b0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
265c0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
265d0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
265e0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
265f0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
26600 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
26610 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
26620 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
26630 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
26640 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
26650 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
26660 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
26670 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
26680 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
26690 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
266a0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
266b0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
266c0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
266d0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
266e0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
266f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
26700 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
26710 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
26720 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
26730 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
26740 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
26750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26760 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
26770 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
26780 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
26790 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
267a0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
267b0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
267c0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
267d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
267e0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
267f0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
26800 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
26810 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
26820 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26830 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
26840 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
26850 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
26860 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
26870 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
26880 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
26890 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
268a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
268b0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
268c0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
268d0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
268e0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
268f0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
26900 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
26910 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
26920 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
26930 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
26940 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
26950 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
26960 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
26970 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
26980 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
26990 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
269a0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
269b0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
269c0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
269d0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
269e0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
269f0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
26a00 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
26a10 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
26a20 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
26a30 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
26a40 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
26a50 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
26a60 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
26a70 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
26a80 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
26a90 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
26aa0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
26ab0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
26ac0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
26ad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
26ae0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
26af0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
26b00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
26b10 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
26b20 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
26b30 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
26b40 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
26b50 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
26b60 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
26b70 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
26b80 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
26b90 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
26ba0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
26bb0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
26bc0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
26bd0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
26be0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
26bf0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
26c00 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
26c10 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
26c20 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
26c30 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
26c40 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
26c50 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
26c60 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
26c70 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
26c80 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
26c90 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
26ca0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
26cb0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
26cc0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
26cd0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
26ce0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
26cf0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
26d00 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
26d10 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
26d20 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
26d30 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
26d40 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
26d50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
26d60 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
26d70 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
26d80 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
26d90 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
26da0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
26db0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
26dc0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
26dd0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
26de0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
26df0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
26e00 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
26e10 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
26e20 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
26e30 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
26e40 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
26e50 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
26e60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
26e70 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
26e80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
26e90 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
26ea0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
26eb0 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
26ec0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
26ed0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
26ee0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26ef0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26f00 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26f10 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26f20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26f30 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
26f40 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26f60 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26f70 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26f80 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26f90 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26fa0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26fb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26fc0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
26fd0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26fe0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26ff0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27000 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
27010 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27020 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
27030 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27040 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
27050 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27060 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
27070 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
27080 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
27090 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
270a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
270b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
270c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
270d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
270e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
270f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
27100 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
27110 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
27120 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
27130 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
27140 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
27150 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
27160 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
27170 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
27180 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27190 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
271a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
271b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
271c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
271d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
271e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
271f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27200 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27210 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27220 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27230 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27240 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27250 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27260 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
27270 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27280 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27290 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
272a0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
272b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
272c0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
272d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
272e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
272f0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27300 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
27310 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27320 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
27330 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27340 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27350 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27360 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27370 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27380 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27390 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
273a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
273b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
273c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
273d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
273e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
273f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
27400 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
27410 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
27420 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
27430 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
27440 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
27450 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
27460 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
27470 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
27480 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
27490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
274a0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
274b0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
274c0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
274d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
274e0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
274f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27500 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
27510 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
27520 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
27530 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
27540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27550 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
27560 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
27570 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
27580 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
27590 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
275a0 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
275b0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
275c0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
275d0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
275e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
275f0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
27600 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
27610 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
27620 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
27630 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
27640 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
27650 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
27660 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
27670 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
27680 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
27690 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
276a0 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
276b0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
276c0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
276d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
276e0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
276f0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
27700 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
27710 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
27720 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
27730 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
27740 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
27750 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
27760 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
27770 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
27780 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
27790 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
277a0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
277b0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
277c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
277d0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
277e0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
277f0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
27800 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
27810 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
27820 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
27830 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
27840 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
27850 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
27860 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
27870 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
27880 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
27890 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
278a0 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
278b0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
278c0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
278d0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
278e0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
278f0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
27900 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
27910 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
27920 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
27930 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
27940 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
27950 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
27960 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
27970 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
27980 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
27990 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
279a0 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
279b0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
279c0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
279d0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
279e0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
279f0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
27a00 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
27a10 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
27a20 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
27a30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27a40 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
27a50 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
27a60 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
27a70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
27a80 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
27a90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
27aa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
27ab0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
27ac0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27ae0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
27af0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
27b00 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
27b10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27b20 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
27b30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27b40 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
27b50 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
27b60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27b70 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
27b80 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
27b90 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
27ba0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
27bb0 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
27bc0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
27bd0 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
27be0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
27bf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
27c00 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
27c10 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
27c20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27c30 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
27c40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
27c50 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
27c60 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
27c70 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
27c80 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
27c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27ca0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
27cb0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
27cc0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
27cd0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
27ce0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
27cf0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
27d00 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
27d10 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
27d20 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
27d30 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
27d40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27d50 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
27d60 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
27d70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
27d80 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
27d90 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
27da0 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
27db0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
27dc0 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
27dd0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
27de0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
27df0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
27e00 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
27e10 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
27e20 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
27e30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
27e40 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
27e50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
27e60 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
27e70 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
27e80 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
27e90 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
27ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
27eb0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
27ec0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
27ed0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
27ee0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
27ef0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
27f00 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
27f10 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
27f20 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
27f30 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
27f40 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
27f50 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
27f60 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
27f70 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
27f80 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
27f90 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
27fa0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
27fb0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
27fc0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
27fd0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
27fe0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
27ff0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
28000 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
28010 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
28020 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
28030 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
28040 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
28050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
28060 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
28070 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
28080 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
28090 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
280a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
280b0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
280c0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
280d0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
280e0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
280f0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
28100 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
28110 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
28120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
28130 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
28140 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
28150 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
28160 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
28170 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
28180 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
28190 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
281a0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
281b0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
281c0 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
281d0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
281e0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
281f0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28200 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
28210 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
28220 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
28230 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
28240 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
28250 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
28260 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
28270 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
28280 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
28290 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
282a0 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
282b0 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
282c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
282d0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
282e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
282f0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
28300 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
28310 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28320 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28330 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28340 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28350 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
28360 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
28370 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
28380 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
28390 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
283a0 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
283b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
283c0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
283d0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
283e0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
283f0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
28400 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28410 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28420 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
28430 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
28440 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
28450 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28460 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
28470 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
28480 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
28490 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
284a0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
284b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
284c0 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
284d0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
284e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
284f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
28500 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28510 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
28520 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
28530 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28540 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
28550 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
28560 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
28570 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
28580 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
28590 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
285a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
285b0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
285c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
285d0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
285e0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
285f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28600 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
28610 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28620 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
28630 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
28640 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
28650 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
28660 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
28670 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
28680 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
28690 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
286a0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
286b0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
286c0 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
286d0 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
286e0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
286f0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
28700 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
28710 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28720 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
28730 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
28740 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28750 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
28760 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
28770 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
28780 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
28790 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
287a0 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
287b0 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
287c0 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
287d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
287e0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
287f0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
28800 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28810 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
28820 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
28830 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
28840 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
28850 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
28860 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
28870 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
28880 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
28890 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
288a0 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
288b0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
288c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
288d0 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
288e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
288f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
28900 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
28910 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
28920 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
28930 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
28940 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
28950 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
28960 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
28970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
28980 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
28990 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
289a0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
289b0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
289c0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
289d0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
289e0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
289f0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
28a00 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
28a10 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
28a20 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
28a30 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
28a40 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
28a50 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
28a60 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
28a70 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
28a80 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
28a90 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
28aa0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
28ab0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
28ac0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
28ad0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
28ae0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
28af0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
28b00 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
28b10 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
28b20 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
28b30 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
28b40 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
28b50 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
28b60 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
28b70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
28b80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
28b90 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
28ba0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
28bb0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
28bc0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
28bd0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
28be0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28bf0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
28c00 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
28c10 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
28c20 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
28c30 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
28c40 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
28c50 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
28c60 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
28c70 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
28c80 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
28c90 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
28ca0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
28cb0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
28cc0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
28cd0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
28ce0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
28cf0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
28d00 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
28d10 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
28d20 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
28d30 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
28d40 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
28d50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28d60 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
28d70 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
28d80 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
28d90 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
28da0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
28db0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
28dc0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
28dd0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
28de0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
28df0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
28e00 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
28e10 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
28e20 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
28e30 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
28e40 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
28e50 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
28e60 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
28e70 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
28e80 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
28e90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
28ea0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
28eb0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28ec0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
28ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28ee0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
28ef0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
28f00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
28f10 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
28f20 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
28f30 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
28f40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
28f50 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
28f60 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
28f70 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
28f80 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
28f90 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
28fa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28fb0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
28fc0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
28fd0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
28fe0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
28ff0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
29000 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
29010 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
29020 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
29030 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29040 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
29050 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
29060 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29070 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
29080 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
29090 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
290a0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
290b0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
290c0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
290d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
290e0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
290f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29100 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
29110 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29120 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
29130 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
29140 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
29150 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
29160 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
29170 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29180 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
29190 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
291a0 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61  6() then that pa
291b0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
291c0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
291d0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
291e0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
291f0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
29200 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
29210 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
29220 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
29230 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
29240 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
29250 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
29260 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
29270 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29280 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
29290 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
292a0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
292b0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
292c0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
292d0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
292e0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
292f0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
29300 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
29310 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
29320 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
29330 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
29340 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
29350 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
29360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29370 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
29380 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
29390 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
293a0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
293b0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
293c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
293d0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
293e0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
293f0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
29400 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
29410 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
29420 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29430 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
29440 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
29450 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29460 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
29470 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
29480 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
29490 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
294a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
294b0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
294c0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
294d0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
294e0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
294f0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
29500 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
29510 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
29520 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
29530 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
29540 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
29550 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
29560 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
29570 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
29580 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
29590 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
295a0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
295b0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
295c0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
295d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
295e0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
295f0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
29600 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
29610 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
29620 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
29630 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
29640 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
29650 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
29660 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
29670 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
29680 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
29690 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
296a0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
296b0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
296c0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
296d0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
296e0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
296f0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
29700 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
29710 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
29720 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
29730 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
29740 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
29750 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
29760 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
29770 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
29780 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
29790 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
297a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
297b0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
297c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
297d0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
297e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
297f0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
29800 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
29810 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
29820 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
29830 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
29840 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
29850 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
29860 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
29870 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
29880 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
29890 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
298a0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
298b0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
298c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
298d0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
298e0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
298f0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
29900 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
29910 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
29920 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
29930 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
29940 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
29950 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
29960 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
29970 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
29980 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
29990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
299a0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
299b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
299c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
299d0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
299e0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
299f0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
29a00 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
29a10 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
29a20 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
29a30 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
29a40 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
29a50 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
29a60 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
29a70 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
29a80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29a90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
29aa0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
29ab0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29ac0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
29ad0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29ae0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
29af0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
29b00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
29b10 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
29b20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29b30 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
29b40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29b50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
29b70 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
29b80 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
29b90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29ba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
29bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29bc0 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
29bd0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29be0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
29bf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29c00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
29c10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29c20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
29c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29c40 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
29c50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
29c60 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
29c70 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29c80 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
29c90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29ca0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29cb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29cc0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
29cd0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
29ce0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
29cf0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
29d00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29d10 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
29d20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29d30 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
29d40 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
29d50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
29d60 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
29d70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29d80 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
29d90 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
29da0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
29db0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
29dc0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
29dd0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
29de0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
29df0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
29e00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29e10 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
29e20 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
29e30 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
29e40 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
29e50 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
29e60 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
29e70 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
29e80 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
29e90 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
29ea0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
29eb0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
29ec0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
29ed0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
29ee0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
29ef0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
29f00 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
29f10 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
29f20 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
29f30 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
29f40 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
29f50 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
29f60 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
29f70 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
29f80 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
29f90 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
29fa0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
29fb0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
29fc0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
29fd0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
29fe0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29ff0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2a000 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2a010 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a020 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2a030 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2a040 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a050 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2a060 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a070 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a080 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2a090 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2a0a0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2a0b0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2a0c0 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
2a0d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a0e0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2a0f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a100 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2a110 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2a120 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2a130 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a140 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2a150 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2a160 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2a170 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2a180 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2a190 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2a1a0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2a1b0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2a1c0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2a1d0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2a1e0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2a1f0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2a200 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2a210 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2a220 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2a230 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2a240 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2a250 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2a260 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2a270 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2a280 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2a290 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2a2a0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2a2b0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2a2c0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2a2d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2a2e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2a2f0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2a300 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2a310 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2a320 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2a330 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2a340 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2a350 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2a360 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2a370 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2a380 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2a390 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2a3a0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2a3b0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2a3c0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2a3d0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2a3e0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2a3f0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2a400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2a410 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2a420 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a430 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a440 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2a450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a460 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a470 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2a480 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a490 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2a4a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2a4b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a4c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a4d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a4e0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
2a4f0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
2a500 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
2a510 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
2a520 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
2a530 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2a540 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2a550 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2a560 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2a570 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2a580 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2a590 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2a5a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2a5b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a5c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2a5d0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2a5e0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2a5f0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2a600 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2a610 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2a620 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2a630 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2a640 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2a650 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2a660 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2a670 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2a680 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2a690 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2a6a0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a6b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2a6c0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2a6d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a6e0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2a6f0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2a700 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a710 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a720 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a740 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2a750 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2a760 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2a770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a780 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2a790 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2a7a0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2a7b0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2a7c0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2a7d0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2a7e0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2a7f0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2a800 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a810 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2a820 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a830 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2a840 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2a850 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2a860 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2a870 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
2a880 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
2a890 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2a8a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2a8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2a8c0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2a8d0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2a8e0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2a8f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2a900 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2a910 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2a920 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2a930 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2a940 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2a950 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2a960 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2a970 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2a980 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2a990 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2a9a0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2a9b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a9c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2a9d0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2a9e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a9f0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2aa00 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2aa10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2aa20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2aa30 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
2aa40 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2aa50 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2aa60 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2aa70 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2aa80 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2aa90 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2aaa0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2aab0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2aac0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2aad0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2aae0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2aaf0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2ab00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2ab10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ab20 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2ab30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ab40 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2ab50 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2ab60 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2ab70 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2ab80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ab90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2aba0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2abb0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2abc0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2abd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2abe0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2abf0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2ac00 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2ac10 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2ac20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2ac30 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2ac40 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2ac50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ac60 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2ac70 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2ac80 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2ac90 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2aca0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2acb0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2acc0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2acd0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2ace0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2acf0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2ad00 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2ad10 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2ad20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2ad30 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2ad40 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2ad50 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2ad60 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2ad70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2ad80 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2ad90 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2ada0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2adb0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2adc0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2add0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2ade0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2adf0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2ae00 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2ae10 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2ae20 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2ae30 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2ae40 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2ae50 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2ae60 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2ae70 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2ae80 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2ae90 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2aea0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2aeb0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2aec0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2aed0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2aee0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2aef0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2af00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2af10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2af20 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2af30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2af40 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
2af50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2af60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2af70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2af80 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
2af90 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
2afa0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
2afb0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2afc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2afd0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
2afe0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
2aff0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2b000 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
2b010 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
2b020 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
2b030 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
2b040 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
2b050 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2b060 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2b070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
2b080 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2b090 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
2b0a0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
2b0b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
2b0c0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
2b0d0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
2b0e0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
2b0f0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
2b100 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
2b110 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
2b120 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
2b130 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
2b140 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2b150 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
2b160 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2b170 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
2b180 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
2b190 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2b1a0 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
2b1b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2b1c0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2b1d0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2b1e0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2b1f0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2b200 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2b210 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2b220 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2b230 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2b240 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
2b250 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
2b260 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
2b270 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
2b280 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
2b290 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
2b2a0 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
2b2b0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
2b2c0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
2b2d0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2b2e0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
2b2f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2b300 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
2b310 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
2b320 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b330 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
2b340 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2b350 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2b360 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
2b370 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
2b380 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
2b390 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
2b3a0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
2b3b0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2b3c0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
2b3d0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
2b3e0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
2b3f0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
2b400 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2b410 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
2b420 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b430 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
2b440 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
2b450 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
2b460 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
2b470 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2b480 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
2b490 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
2b4a0 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
2b4b0 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
2b4c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2b4d0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
2b4e0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
2b4f0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
2b500 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
2b510 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
2b520 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
2b530 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
2b540 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
2b550 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
2b560 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
2b570 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
2b580 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
2b590 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
2b5a0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
2b5b0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
2b5c0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
2b5d0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
2b5e0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
2b5f0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
2b600 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
2b610 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
2b620 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2b630 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
2b640 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
2b650 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
2b660 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
2b670 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2b680 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2b690 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
2b6a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2b6b0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
2b6c0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
2b6d0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
2b6e0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
2b6f0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2b700 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
2b710 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
2b720 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2b730 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2b740 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
2b750 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2b760 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
2b770 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
2b780 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
2b790 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
2b7a0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
2b7b0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
2b7c0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2b7d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2b7e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2b7f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2b800 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b810 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2b820 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b830 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2b840 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2b850 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b860 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2b870 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b880 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2b890 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b8a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2b8b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2b8c0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2b8d0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2b8e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b8f0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2b900 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b910 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b920 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2b930 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2b940 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b950 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2b960 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2b970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2b980 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2b990 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2b9a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b9b0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2b9c0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2b9d0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
2b9e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2b9f0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2ba00 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2ba10 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2ba20 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2ba30 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2ba40 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2ba50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2ba60 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2ba70 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2ba80 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2ba90 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2baa0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2bab0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2bac0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2bad0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2bae0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2baf0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2bb00 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2bb10 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2bb20 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2bb30 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2bb40 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2bb50 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2bb60 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2bb70 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2bb80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2bb90 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2bba0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2bbb0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2bbc0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2bbd0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2bbe0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2bbf0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2bc00 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2bc10 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2bc20 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2bc30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2bc40 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2bc50 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2bc60 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2bc70 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2bc80 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2bc90 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2bca0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2bcb0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2bcc0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2bcd0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2bce0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2bcf0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2bd00 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2bd10 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2bd20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2bd30 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2bd40 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2bd50 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2bd60 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2bd70 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2bd80 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2bd90 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2bda0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2bdb0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2bdc0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2bdd0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2bde0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2bdf0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2be00 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2be10 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2be20 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
2be30 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2be40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2be50 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2be60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2be70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2be80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2be90 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2bea0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2beb0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2bec0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2bed0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2bee0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2bef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bf00 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2bf10 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2bf20 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2bf30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2bf40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bf50 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2bf60 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2bf70 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2bf80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2bf90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2bfa0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2bfb0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2bfc0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2bfd0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2bfe0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2bff0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2c000 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2c010 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2c020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c030 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2c040 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2c050 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2c060 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2c070 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2c080 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2c090 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c0a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c0b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2c0c0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2c0d0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2c0e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c0f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c100 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2c110 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2c120 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2c130 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2c140 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2c150 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2c160 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2c170 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2c180 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2c190 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2c1a0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2c1b0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2c1c0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2c1d0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2c1e0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2c1f0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2c200 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2c210 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2c220 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2c230 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c240 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2c250 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2c260 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2c270 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2c280 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2c290 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2c2a0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2c2b0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c2c0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2c2d0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2c2e0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2c2f0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2c300 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2c310 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2c320 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2c330 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2c340 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2c350 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2c360 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2c370 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2c380 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2c390 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c3a0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2c3b0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2c3c0 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2c3d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2c3e0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2c3f0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2c400 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2c410 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2c420 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2c430 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2c440 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2c450 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2c460 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2c470 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2c480 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2c490 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2c4a0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2c4b0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2c4c0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2c4d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c4e0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2c4f0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2c500 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2c510 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2c520 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2c530 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2c540 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2c550 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2c560 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2c570 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2c580 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2c590 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2c5a0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2c5b0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2c5c0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2c5d0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2c5e0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2c5f0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2c600 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2c610 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2c620 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2c630 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2c640 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2c650 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2c660 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2c670 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2c680 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2c690 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2c6a0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2c6b0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2c6c0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2c6d0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2c6e0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2c6f0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2c700 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c710 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2c720 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2c730 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2c740 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2c750 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2c760 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2c770 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2c780 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2c790 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2c7a0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2c7b0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2c7c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2c7d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2c7e0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c7f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2c800 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2c810 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2c820 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2c830 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2c840 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2c850 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2c860 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2c870 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2c880 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2c890 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2c8a0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2c8b0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2c8c0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2c8d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2c8e0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2c8f0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2c900 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2c910 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2c920 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2c930 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2c940 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2c950 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2c960 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2c970 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2c980 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2c990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c9a0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2c9b0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2c9c0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2c9d0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2c9e0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2c9f0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2ca00 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2ca10 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2ca20 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2ca30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ca40 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2ca50 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2ca60 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2ca70 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2ca80 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2ca90 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2caa0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2cab0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2cac0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2cad0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2cae0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2caf0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2cb00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2cb10 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2cb20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2cb30 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2cb40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2cb50 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2cb60 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2cb70 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2cb80 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2cb90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2cba0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2cbb0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2cbc0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2cbd0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2cbe0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2cbf0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2cc00 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2cc10 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2cc20 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2cc30 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2cc40 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2cc50 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2cc60 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2cc70 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2cc80 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2cc90 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2cca0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2ccb0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2ccc0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2ccd0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2cce0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2ccf0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2cd00 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2cd10 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2cd20 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2cd30 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2cd40 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2cd50 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2cd60 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2cd70 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2cd80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2cd90 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2cda0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2cdb0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2cdc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2cdd0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2cde0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2cdf0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2ce00 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2ce10 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2ce20 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2ce30 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2ce40 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2ce50 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2ce60 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2ce70 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2ce80 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2ce90 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2cea0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2ceb0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2cec0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2ced0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2cee0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2cef0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2cf00 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2cf10 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2cf20 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2cf30 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2cf40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cf50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2cf60 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2cf70 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2cf80 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2cf90 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2cfa0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2cfb0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2cfc0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2cfd0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2cfe0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2cff0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
2d000 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2d010 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d020 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2d030 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2d040 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2d050 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2d060 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2d070 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2d080 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2d090 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2d0a0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2d0b0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2d0c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2d0d0 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2d0e0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2d0f0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2d100 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2d110 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2d120 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2d130 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2d140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2d150 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2d160 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2d170 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2d180 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2d190 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2d1a0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2d1b0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2d1c0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2d1d0 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2d1e0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2d1f0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2d200 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2d210 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2d220 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2d230 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2d240 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2d250 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2d260 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2d270 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2d280 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2d290 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2d2a0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2d2b0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2d2c0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2d2d0 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2d2e0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2d2f0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2d300 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2d310 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2d320 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2d330 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2d340 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2d350 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2d360 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2d370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2d380 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2d390 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d3a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2d3b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d3d0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2d3e0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2d3f0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2d400 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2d410 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2d420 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2d430 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2d440 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2d450 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2d460 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2d470 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2d480 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2d490 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2d4a0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2d4b0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2d4c0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2d4d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2d4e0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2d4f0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2d500 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2d510 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2d520 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2d530 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2d540 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d550 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2d560 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2d570 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2d580 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2d590 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2d5a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2d5b0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2d5c0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2d5d0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2d5e0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2d5f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2d600 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2d610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2d620 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2d630 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2d640 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2d650 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2d660 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2d670 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2d680 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2d690 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2d6a0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2d6b0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2d6c0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2d6d0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2d6e0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2d6f0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2d700 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2d710 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2d720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2d730 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2d740 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2d750 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2d760 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2d770 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2d780 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2d790 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2d7a0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2d7b0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2d7c0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2d7d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2d7e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2d7f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d800 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2d810 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2d820 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2d830 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2d840 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2d850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d860 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2d870 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2d880 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2d890 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2d8a0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2d8b0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2d8c0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2d8d0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2d8e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2d8f0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2d900 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2d910 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2d920 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d930 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2d940 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2d950 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d960 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2d970 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2d980 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2d990 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2d9a0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2d9b0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2d9c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2d9d0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2d9e0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2d9f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2da00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2da10 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2da20 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2da30 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2da40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2da50 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2da60 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2da70 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2da80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2da90 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2daa0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2dab0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2dac0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2dad0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2dae0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2daf0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2db00 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2db10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2db20 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2db30 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2db40 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2db50 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2db60 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2db70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2db80 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2db90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2dba0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dbb0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2dbc0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2dbd0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2dbe0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2dbf0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2dc00 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2dc10 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2dc20 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2dc30 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2dc40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dc50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2dc60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2dc70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2dc80 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2dc90 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2dca0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2dcb0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2dcc0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2dcd0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2dce0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2dcf0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2dd00 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2dd10 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2dd20 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2dd30 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2dd40 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2dd50 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2dd60 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2dd70 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2dd80 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2dd90 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2dda0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2ddb0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2ddc0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2ddd0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2dde0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2ddf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2de00 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2de10 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2de20 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2de30 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2de40 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2de50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2de60 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2de70 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2de80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2de90 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2dea0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2deb0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2dec0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ded0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2dee0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2def0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2df00 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2df10 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2df20 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2df30 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2df40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2df50 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2df60 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2df70 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2df80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2df90 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2dfa0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2dfb0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2dfc0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2dfd0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2dfe0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2dff0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2e000 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2e010 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2e020 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2e030 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e040 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2e050 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e060 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2e070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e080 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2e090 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2e0a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e0b0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2e0c0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2e0d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e0e0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2e0f0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2e100 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e110 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2e120 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e130 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2e140 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2e150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e160 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2e170 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2e180 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2e190 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2e1a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2e1b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e1c0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2e1d0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2e1e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e1f0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2e200 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2e210 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2e220 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2e230 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2e240 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2e250 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e260 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2e270 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e280 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2e290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e2a0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2e2b0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2e2c0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2e2d0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2e2e0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2e2f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e300 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2e310 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2e320 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2e330 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2e340 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2e350 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2e360 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2e370 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2e380 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2e390 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2e3a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2e3b0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2e3c0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2e3d0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2e3e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2e3f0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2e400 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2e410 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2e420 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2e430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e440 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2e450 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2e460 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2e470 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2e480 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2e490 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2e4a0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2e4b0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2e4c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e4d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2e4e0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2e4f0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2e500 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2e510 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2e520 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e530 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2e540 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e550 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2e560 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2e570 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2e580 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2e590 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2e5a0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2e5b0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2e5c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e5d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2e5e0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2e5f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2e600 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2e610 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2e620 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2e630 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2e640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2e650 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2e660 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2e670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2e680 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2e690 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2e6a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2e6b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e6c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2e6d0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2e6e0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2e6f0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2e700 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2e710 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2e720 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2e730 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2e740 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2e750 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2e760 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2e770 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2e780 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2e790 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2e7a0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2e7b0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2e7c0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2e7d0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2e7e0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2e7f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2e800 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2e810 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2e820 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2e830 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2e840 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2e850 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2e860 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2e870 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2e880 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2e890 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2e8a0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2e8b0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2e8c0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2e8d0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2e8e0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2e8f0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2e900 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2e910 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2e920 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2e930 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
2e940 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2e950 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2e960 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e970 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2e980 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2e990 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2e9a0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2e9b0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2e9c0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2e9d0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2e9e0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2e9f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2ea00 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2ea10 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2ea20 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2ea30 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2ea40 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2ea50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ea60 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2ea70 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2ea80 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2ea90 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2eaa0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2eab0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b    BLOB    <td> [
2eac0 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a  CAST] to BLOB.**
2ead0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2eae0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2eaf0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2eb00 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2eb10 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2eb20 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2eb30 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2eb40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2eb50 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2eb60 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2eb70 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2eb80 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2eb90 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2eba0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2ebb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2ebc0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2ebd0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2ebe0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
2ebf0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2ec00 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2ec10 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2ec20 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2ec30 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2ec40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2ec50 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2ec60 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2ec70 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2ec80 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2ec90 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2eca0 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2ecb0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2ecc0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2ecd0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2ece0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2ecf0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2ed00 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2ed10 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2ed20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2ed30 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2ed40 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2ed50 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2ed60 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2ed70 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2ed80 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2ed90 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2eda0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2edb0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2edc0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2edd0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ede0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2edf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ee00 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2ee10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ee20 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2ee30 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2ee40 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2ee50 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2ee60 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2ee70 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2ee80 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2ee90 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2eea0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2eeb0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2eec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2eed0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2eee0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2eef0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2ef00 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2ef10 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2ef20 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2ef30 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2ef40 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2ef50 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2ef60 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2ef70 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2ef80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ef90 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2efa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2efb0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2efc0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2efd0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2efe0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2eff0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2f000 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2f010 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2f020 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2f030 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f040 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2f050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f060 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2f070 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2f080 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2f090 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2f0a0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2f0b0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2f0c0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2f0d0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2f0e0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2f0f0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2f100 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2f110 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2f120 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2f130 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2f140 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2f150 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2f160 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2f170 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2f180 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2f190 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2f1a0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2f1b0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2f1c0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2f1d0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2f1e0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2f1f0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2f200 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2f210 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2f220 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2f230 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2f240 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2f250 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2f260 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2f270 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2f280 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2f290 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2f2a0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2f2b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2f2c0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2f2d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f2e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2f2f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f300 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2f310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f320 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2f330 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2f340 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2f350 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f360 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f370 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2f380 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2f390 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2f3a0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2f3b0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2f3c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f3d0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2f3e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f3f0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2f400 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2f410 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2f420 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2f430 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2f440 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2f450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f460 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2f470 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2f480 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2f490 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2f4a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f4b0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2f4c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2f4d0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2f4e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f4f0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2f500 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2f510 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2f520 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2f530 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2f540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f550 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2f560 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2f570 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2f580 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f590 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2f5a0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2f5b0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2f5c0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2f5d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f5e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2f5f0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2f600 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2f610 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2f620 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2f630 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2f640 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2f650 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2f660 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2f670 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2f680 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
2f690 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2f6a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f6b0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2f6c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2f6d0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2f6e0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2f6f0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2f700 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2f710 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2f720 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2f730 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2f740 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2f750 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2f760 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2f770 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2f780 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2f790 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2f7a0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2f7b0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2f7c0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2f7d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2f7e0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2f7f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2f800 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2f810 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f820 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2f830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f840 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2f850 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2f860 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2f870 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f880 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2f890 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2f8a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2f8b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f8c0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2f8d0 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2f8e0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2f8f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f900 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2f910 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2f920 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2f930 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f940 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2f950 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2f960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2f970 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2f980 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2f990 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2f9a0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2f9b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f9c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f9d0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2f9e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2f9f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2fa00 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2fa10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2fa20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2fa30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fa40 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2fa50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2fa60 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2fa70 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2fa80 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2fa90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2faa0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2fab0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2fac0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2fad0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2fae0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2faf0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2fb00 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2fb10 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2fb20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2fb30 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2fb40 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2fb50 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2fb60 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2fb70 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2fb80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2fb90 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2fba0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2fbb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2fbc0 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2fbd0 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2fbe0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2fbf0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2fc00 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2fc10 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2fc20 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2fc30 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2fc40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2fc50 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2fc60 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2fc70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2fc80 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2fc90 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2fca0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2fcb0 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2fcc0 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2fcd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2fce0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2fcf0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2fd00 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2fd10 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2fd20 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2fd30 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2fd40 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2fd50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2fd60 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2fd70 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2fd80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2fd90 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2fda0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2fdb0 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2fdc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2fdd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2fde0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2fdf0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2fe00 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2fe10 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2fe20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fe30 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2fe40 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2fe50 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2fe60 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2fe70 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2fe80 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2fe90 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2fea0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2feb0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2fec0 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2fed0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2fee0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2fef0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2ff00 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2ff10 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2ff20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2ff30 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2ff40 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2ff50 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2ff60 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2ff70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
2ff80 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2ff90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2ffa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2ffb0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2ffc0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2ffd0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ffe0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2fff0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
30000 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
30010 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
30020 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
30030 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
30040 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
30050 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
30060 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
30070 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
30080 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
30090 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
300a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
300b0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
300c0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
300d0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
300e0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
300f0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
30100 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
30110 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
30120 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
30130 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
30140 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
30150 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30160 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
30170 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
30180 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
30190 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
301a0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
301b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
301c0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
301d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
301e0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
301f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
30200 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
30210 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
30220 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
30230 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
30240 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
30250 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
30260 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
30270 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
30280 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
30290 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
302a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
302b0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
302c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
302d0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
302e0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
302f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
30300 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
30310 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
30320 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
30330 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
30340 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
30350 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
30360 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
30370 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
30380 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
30390 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
303a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
303b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
303c0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
303d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
303e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
303f0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
30400 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
30410 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
30420 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
30430 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
30440 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
30450 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30460 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
30470 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
30480 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30490 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
304a0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
304b0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
304c0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
304d0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
304e0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
304f0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
30500 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
30510 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
30520 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
30530 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
30540 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
30550 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
30560 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
30570 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
30580 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
30590 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
305a0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
305b0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
305c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
305d0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
305e0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
305f0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
30600 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
30610 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
30620 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
30630 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
30640 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
30650 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
30660 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
30670 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
30680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
30690 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
306a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
306b0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
306c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
306d0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
306e0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
306f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
30700 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30710 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
30720 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
30730 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
30740 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
30750 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
30760 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
30770 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
30780 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
30790 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
307a0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
307b0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
307c0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
307d0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
307e0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
307f0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
30800 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
30810 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
30820 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
30830 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
30840 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
30850 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
30860 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
30870 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
30880 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
30890 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
308a0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
308b0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
308c0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
308d0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
308e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
308f0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
30900 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
30910 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
30920 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
30930 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30940 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
30950 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
30960 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
30970 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
30980 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30990 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
309a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
309b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
309c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
309d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
309e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
309f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
30a00 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
30a10 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
30a20 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
30a30 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
30a40 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
30a50 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
30a60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
30a70 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
30a80 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
30a90 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
30aa0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
30ab0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
30ac0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
30ad0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
30ae0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
30af0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
30b00 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
30b10 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
30b20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
30b30 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
30b40 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
30b50 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
30b60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30b70 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
30b80 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
30b90 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
30ba0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
30bb0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
30bc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30bd0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
30be0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
30bf0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
30c00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30c10 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
30c20 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
30c30 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
30c40 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
30c50 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
30c60 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
30c70 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
30c80 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
30c90 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
30ca0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
30cb0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
30cc0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
30cd0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
30ce0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
30cf0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
30d00 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
30d10 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
30d20 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
30d30 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
30d40 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
30d50 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
30d60 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
30d70 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
30d80 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
30d90 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
30da0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
30db0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
30dc0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
30dd0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
30de0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
30df0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
30e00 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
30e10 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
30e20 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
30e30 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
30e40 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
30e50 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
30e60 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
30e70 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
30e80 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
30e90 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
30ea0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
30eb0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
30ec0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
30ed0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
30ee0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
30ef0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
30f00 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
30f10 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
30f20 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
30f30 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
30f40 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
30f50 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
30f60 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
30f70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
30f80 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
30f90 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
30fa0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
30fb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
30fc0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
30fd0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
30fe0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
30ff0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
31000 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
31010 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
31020 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
31030 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
31040 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
31050 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
31060 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
31070 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
31080 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
31090 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
310a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
310b0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
310c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
310d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
310e0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
310f0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
31100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
31110 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
31120 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
31130 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
31140 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
31150 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
31160 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
31170 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
31180 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
31190 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
311a0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
311b0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
311c0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
311d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
311e0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
311f0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
31200 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
31210 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
31220 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
31230 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
31240 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31250 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31260 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
31270 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
31280 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
31290 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
312a0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
312b0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
312c0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
312d0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
312e0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
312f0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
31300 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
31310 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
31320 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
31330 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
31340 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
31350 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
31360 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
31370 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31380 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
31390 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
313a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
313b0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
313c0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
313d0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
313e0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
313f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
31400 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
31410 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
31420 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
31430 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
31440 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31450 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31460 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
31470 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
31480 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
31490 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
314a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
314b0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
314c0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
314d0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
314e0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
314f0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
31500 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
31510 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
31520 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
31530 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
31540 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31550 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
31560 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
31570 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
31580 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
31590 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
315a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
315b0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
315c0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
315d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
315e0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
315f0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
31600 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
31610 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
31620 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
31630 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
31640 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
31650 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
31660 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
31670 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
31680 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
31690 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
316a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
316b0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
316c0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
316d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
316e0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
316f0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
31700 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
31710 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
31720 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
31730 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
31740 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
31750 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
31760 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
31770 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
31780 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
31790 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
317a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
317b0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
317c0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
317d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
317e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
317f0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
31800 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
31810 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
31820 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
31830 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
31840 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31850 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
31860 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
31870 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
31880 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
31890 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
318a0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
318b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
318c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
318d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
318e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
318f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
31900 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
31910 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
31920 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
31930 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
31940 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31950 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31960 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
31970 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31980 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31990 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
319a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
319b0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
319c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
319d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
319e0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
319f0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
31a00 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
31a10 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
31a20 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
31a30 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31a40 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31a50 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31a60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31a70 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31a80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31a90 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31aa0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31ab0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31ac0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
31ad0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31ae0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31af0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
31b00 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
31b10 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
31b20 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
31b30 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
31b40 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
31b50 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
31b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31b70 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31b80 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31b90 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31ba0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31bb0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31bc0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
31bd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
31be0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
31bf0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
31c00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
31c10 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
31c20 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
31c30 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
31c40 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
31c50 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
31c60 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
31c70 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
31c80 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
31c90 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
31ca0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
31cb0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
31cc0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
31cd0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
31ce0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
31cf0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
31d00 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
31d10 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
31d20 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
31d30 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
31d40 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
31d50 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
31d60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31d70 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
31d80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
31d90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
31da0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
31db0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
31dc0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
31dd0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
31de0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
31df0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
31e00 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
31e10 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
31e20 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
31e30 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
31e40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
31e50 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
31e60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31e70 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
31e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
31e90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31ea0 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
31eb0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
31ec0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
31ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
31ee0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
31ef0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
31f00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
31f10 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
31f20 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
31f30 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
31f40 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
31f50 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
31f60 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
31f70 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
31f80 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
31f90 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
31fa0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
31fb0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
31fc0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
31fd0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
31fe0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
31ff0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
32000 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
32010 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
32020 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
32030 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
32040 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
32050 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
32060 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
32070 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
32080 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
32090 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
320a0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
320b0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
320c0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
320d0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
320e0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
320f0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
32100 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
32110 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32120 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
32130 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
32140 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
32150 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
32160 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32170 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
32180 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
32190 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
321a0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
321b0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
321c0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
321d0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
321e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
321f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
32200 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
32210 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
32220 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
32230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
32240 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
32250 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
32260 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
32270 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
32280 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
32290 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
322a0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
322b0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
322c0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
322d0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
322e0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
322f0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
32300 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
32310 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
32320 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
32330 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
32340 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
32350 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
32360 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
32370 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
32380 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
32390 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
323a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
323b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
323c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
323d0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
323e0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
323f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
32400 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
32410 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
32420 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
32430 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
32440 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
32450 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
32460 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32470 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
32480 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
32490 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
324a0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
324b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
324c0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
324d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
324e0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
324f0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
32500 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
32510 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
32520 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32530 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
32540 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32550 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32560 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
32570 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
32580 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
32590 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
325a0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
325b0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
325c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
325d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
325e0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
325f0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
32600 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
32610 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
32620 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
32630 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
32640 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
32650 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
32660 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32670 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
32680 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
32690 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
326a0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
326b0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
326c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
326d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
326e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
326f0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
32700 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
32710 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
32720 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
32730 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
32740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32750 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
32760 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32770 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
32780 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
32790 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
327a0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
327b0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
327c0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
327d0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
327e0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
327f0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
32800 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
32810 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
32820 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
32830 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
32840 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
32850 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
32860 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
32870 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
32880 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
32890 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
328a0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
328b0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
328c0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
328d0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
328e0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
328f0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
32900 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
32910 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
32920 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
32930 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
32940 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
32950 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
32960 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
32970 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
32980 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
32990 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
329a0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
329b0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
329c0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
329d0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
329e0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
329f0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
32a00 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
32a10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
32a20 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
32a30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
32a40 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
32a50 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
32a60 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
32a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32a80 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
32a90 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
32aa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
32ab0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
32ac0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32ad0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
32ae0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32af0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
32b00 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
32b10 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
32b20 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
32b30 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
32b40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
32b50 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
32b60 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
32b70 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
32b80 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
32b90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
32ba0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
32bb0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
32bc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
32bd0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32be0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
32bf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32c00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
32c10 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
32c20 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
32c30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32c40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
32c50 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
32c60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
32c70 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
32c80 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
32c90 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
32ca0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32cb0 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
32cc0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
32cd0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
32ce0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
32cf0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
32d00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32d10 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
32d20 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
32d30 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
32d40 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32d50 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32d60 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32d70 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
32d80 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
32d90 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
32da0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
32db0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
32dc0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
32dd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
32de0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
32df0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32e00 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
32e10 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
32e20 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
32e30 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
32e40 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
32e50 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
32e60 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
32e70 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
32e80 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
32e90 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
32ea0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
32eb0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
32ec0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
32ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
32ee0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32ef0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
32f00 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
32f10 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
32f20 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
32f30 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
32f40 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
32f50 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
32f60 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
32f70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
32f80 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
32f90 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
32fa0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
32fb0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
32fc0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32fd0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
32fe0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
32ff0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
33000 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
33010 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
33020 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
33030 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
33040 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
33050 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
33060 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
33070 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
33080 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
33090 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
330a0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
330b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
330c0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
330d0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
330e0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
330f0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
33100 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
33110 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
33120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
33130 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
33140 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
33150 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
33160 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
33170 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
33180 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33190 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
331a0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
331b0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
331c0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
331d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
331e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
331f0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
33200 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
33210 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
33220 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
33230 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
33240 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
33250 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
33260 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
33270 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
33280 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
33290 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
332a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
332b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
332c0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
332d0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
332e0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
332f0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
33300 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
33310 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
33320 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33330 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33340 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33350 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
33360 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
33370 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
33380 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
33390 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
333a0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
333b0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
333c0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
333d0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
333e0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
333f0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
33400 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33410 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
33420 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
33430 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
33440 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
33450 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
33460 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
33470 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
33480 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
33490 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
334a0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
334b0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
334c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
334d0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
334e0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
334f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
33500 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
33510 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
33520 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
33530 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
33540 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
33550 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
33560 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
33570 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
33580 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
33590 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
335a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
335b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
335c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
335d0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
335e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
335f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
33600 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
33610 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33620 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
33630 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
33640 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
33650 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
33660 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
33670 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33680 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
33690 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
336a0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
336b0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
336c0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
336d0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
336e0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
336f0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
33700 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33710 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
33720 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33730 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
33740 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
33750 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
33760 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33770 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
33780 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
33790 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
337a0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
337b0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
337c0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
337d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
337e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
337f0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
33800 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
33810 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
33820 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
33830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
33840 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
33850 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
33860 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33870 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
33880 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
33890 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
338a0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
338b0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
338c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
338d0 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
338e0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
338f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33900 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
33910 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33920 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
33930 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
33940 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
33950 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
33960 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
33970 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
33980 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
33990 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
339a0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
339b0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
339c0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
339d0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
339e0 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ta.**.** These f
339f0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
33a00 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
33a10 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
33a20 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
33a30 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
33a40 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
33a50 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
33a60 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
33a70 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
33a80 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
33a90 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
33aa0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
33ab0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
33ac0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
33ad0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
33ae0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
33af0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
33b00 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
33b10 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
33b20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
33b30 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
33b40 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
33b50 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
33b60 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
33b70 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
33b80 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
33b90 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
33ba0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
33bb0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
33bc0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
33bd0 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
33be0 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
33bf0 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
33c00 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
33c10 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
33c20 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33c30 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
33c40 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
33c50 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
33c60 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
33c70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33c80 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
33c90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
33ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
33cb0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
33cc0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
33cd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33ce0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
33cf0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
33d00 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
33d10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33d20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33d30 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
33d40 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
33d50 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33d60 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
33d70 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
33d80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
33d90 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
33da0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
33db0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
33dc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33dd0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
33de0 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
33df0 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
33e00 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
33e10 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
33e20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33e30 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
33e40 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
33e50 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
33e60 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
33e70 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
33e80 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
33e90 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33ea0 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
33eb0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
33ec0 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
33ed0 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
33ee0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
33ef0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
33f00 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
33f10 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
33f20 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
33f30 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
33f40 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
33f50 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
33f60 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
33f70 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
33f80 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
33f90 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
33fa0 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
33fb0 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
33fc0 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
33fd0 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
33fe0 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
33ff0 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
34000 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
34010 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
34020 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
34030 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
34040 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
34050 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
34060 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34070 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
34080 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
34090 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
340a0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
340b0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
340c0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
340d0 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
340e0 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
340f0 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
34100 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
34110 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
34120 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
34130 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
34140 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
34150 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
34160 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
34170 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
34180 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
34190 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
341a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
341b0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
341c0 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
341d0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
341e0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
341f0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
34200 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
34210 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
34220 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34230 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
34240 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
34250 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
34260 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
34270 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
34280 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34290 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
342a0 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
342b0 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
342c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
342d0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
342e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
342f0 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
34300 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
34310 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
34320 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
34330 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
34340 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
34350 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
34360 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
34370 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
34380 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
34390 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
343a0 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
343b0 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
343c0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
343d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
343e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
343f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
34400 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
34410 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
34420 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
34430 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
34440 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34450 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
34460 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34470 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
34480 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34490 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
344a0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
344b0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
344c0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
344d0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
344e0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
344f0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
34500 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
34510 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
34520 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
34530 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
34540 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
34550 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
34560 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34570 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
34580 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
34590 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
345a0 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
345b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
345c0 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
345d0 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
345e0 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
345f0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
34600 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
34610 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
34620 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
34630 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
34640 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
34650 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
34660 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
34670 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
34680 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
34690 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
346a0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
346b0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
346c0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
346d0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
346e0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
346f0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
34700 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
34710 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
34720 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
34730 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
34740 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
34750 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
34760 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
34770 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34780 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
34790 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
347a0 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
347b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
347c0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
347d0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
347e0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
347f0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
34800 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
34810 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
34820 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
34830 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
34840 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
34850 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
34860 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
34870 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34880 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
34890 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
348a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
348b0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
348c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
348d0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
348e0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
348f0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
34900 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
34910 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
34920 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
34930 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
34940 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
34950 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34960 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
34970 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
34980 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
34990 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
349a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
349b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
349c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
349d0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
349e0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
349f0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34a00 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34a10 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
34a20 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
34a30 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
34a40 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
34a50 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
34a60 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
34a70 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
34a80 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
34a90 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
34aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ab0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
34ac0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
34ad0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
34ae0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34af0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34b00 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
34b10 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
34b20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
34b30 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
34b40 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
34b50 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
34b60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
34b70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b80 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
34b90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
34ba0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
34bb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34bc0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34bd0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
34be0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
34bf0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
34c00 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
34c10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34c20 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34c40 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
34c50 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
34c60 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
34c70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
34c80 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
34c90 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
34ca0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
34cb0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
34cc0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
34cd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ce0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
34cf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34d00 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
34d10 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
34d20 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
34d30 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34d40 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
34d50 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
34d60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34d70 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
34d80 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
34d90 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
34da0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
34db0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
34dc0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
34dd0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
34de0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34df0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34e10 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34e20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34e30 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
34e40 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34e50 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
34e60 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
34e70 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
34e80 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
34e90 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
34ea0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34eb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
34ec0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
34ed0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ee0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
34ef0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
34f00 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
34f10 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
34f20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
34f30 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
34f40 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
34f50 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
34f60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34f70 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34f80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34f90 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
34fa0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
34fb0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
34fc0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
34fd0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
34fe0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
34ff0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
35000 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
35010 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
35020 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
35030 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
35040 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
35050 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35060 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
35070 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
35080 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
35090 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
350a0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
350b0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
350c0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
350d0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
350e0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
350f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
35100 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
35110 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
35120 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
35130 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35140 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
35150 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
35160 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
35170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35180 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35190 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
351a0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
351b0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
351c0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
351d0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
351e0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
351f0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
35200 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
35210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35220 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
35230 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
35240 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
35250 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
35260 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
35270 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
35280 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
35290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
352a0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
352b0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
352c0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
352d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
352e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
352f0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
35300 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
35310 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
35320 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
35330 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35340 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
35350 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35360 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
35370 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35380 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35390 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
353a0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
353b0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
353c0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
353d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
353e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
353f0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
35400 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
35410 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
35420 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35430 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35440 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
35450 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35460 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
35470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35480 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
35490 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
354a0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
354b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
354c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
354d0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
354e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
354f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35500 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35510 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
35520 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
35530 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
35540 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
35550 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
35560 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
35570 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
35580 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
35590 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
355a0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
355b0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
355c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
355d0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
355e0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
355f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35600 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
35610 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
35620 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35640 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35650 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
35660 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35670 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
35680 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
35690 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
356a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
356b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
356c0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
356d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
356e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
356f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
35700 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
35710 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
35720 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
35730 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
35740 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
35750 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35760 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
35770 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35780 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
35790 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
357a0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
357b0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
357c0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
357d0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
357e0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
357f0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
35800 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
35810 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
35820 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
35830 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
35840 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
35850 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
35860 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
35870 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
35880 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
35890 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
358a0 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
358b0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
358c0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
358d0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
358e0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
358f0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
35900 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
35910 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
35920 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
35930 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
35940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35950 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35960 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35970 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35980 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
35990 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
359a0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
359b0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
359c0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
359d0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
359e0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
359f0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
35a00 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
35a10 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
35a20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
35a30 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
35a40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
35a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35a60 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
35a70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
35a80 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
35a90 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
35aa0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
35ab0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
35ac0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
35ad0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
35ae0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
35af0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
35b00 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
35b10 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
35b20 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
35b30 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
35b40 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
35b50 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
35b60 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
35b70 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
35b80 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
35b90 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35ba0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35bb0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
35bc0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35bd0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
35be0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
35bf0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
35c00 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
35c10 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
35c20 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
35c30 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
35c40 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
35c50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
35c60 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
35c70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35c80 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
35c90 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35ca0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
35cb0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
35cc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35cd0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
35ce0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
35cf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35d00 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
35d10 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
35d20 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
35d30 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35d40 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35d50 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
35d60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
35d70 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
35d80 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
35d90 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
35da0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
35db0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
35dc0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
35dd0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
35de0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
35df0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
35e00 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
35e10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35e20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
35e30 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
35e40 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
35e50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35e60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
35e70 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
35e80 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
35e90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
35ea0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
35eb0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
35ec0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
35ed0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35ee0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
35ef0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
35f00 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
35f10 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
35f20 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
35f30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35f40 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
35f50 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
35f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
35f70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
35f80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
35f90 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
35fa0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35fb0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
35fc0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35fd0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35fe0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
35ff0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36000 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
36010 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
36020 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
36030 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36050 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
36060 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36070 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
36080 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36090 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
360a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
360b0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
360c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
360d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
360e0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
360f0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
36100 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
36110 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36120 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
36130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36140 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
36150 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36160 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
36170 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36180 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
36190 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
361a0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
361b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
361c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
361d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
361e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
361f0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
36200 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
36210 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
36220 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
36230 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
36240 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36250 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36260 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36270 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36280 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
36290 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
362a0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
362b0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
362c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
362d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
362e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
362f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
36300 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36310 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
36320 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36330 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
36340 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
36350 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36370 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
36380 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36390 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
363a0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
363b0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
363c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
363d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
363e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
363f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
36400 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36410 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
36420 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
36430 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
36440 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
36450 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
36460 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
36470 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
36480 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
36490 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
364a0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
364b0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
364c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
364d0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
364e0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
364f0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
36500 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
36510 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
36520 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
36530 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36540 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
36550 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36560 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
36570 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
36580 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
36590 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
365a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
365b0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
365c0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
365d0 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
365e0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
365f0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
36600 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
36610 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
36620 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
36630 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
36640 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
36650 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
36660 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
36670 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
36680 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
36690 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
366a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
366b0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
366c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
366d0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
366e0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
366f0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
36700 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
36710 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
36720 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
36730 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
36740 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
36750 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36760 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
36770 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
36780 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
36790 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
367a0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
367b0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
367c0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
367d0 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
367e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
367f0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
36800 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36810 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
36820 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
36830 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
36840 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
36850 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
36860 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
36870 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
36880 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36890 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
368a0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
368b0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
368c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
368d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
368e0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
368f0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
36900 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
36910 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
36920 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36930 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
36940 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
36950 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
36960 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
36970 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
36980 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
36990 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
369a0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
369b0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
369c0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
369d0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
369e0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
369f0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
36a00 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
36a10 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
36a20 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
36a30 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
36a40 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
36a50 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
36a60 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
36a70 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
36a80 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
36a90 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
36aa0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
36ab0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
36ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
36ad0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
36ae0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
36af0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
36b00 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
36b10 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
36b20 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
36b30 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
36b40 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
36b50 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
36b60 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
36b70 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
36b80 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
36b90 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
36ba0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
36bb0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
36bc0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
36bd0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
36be0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
36bf0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
36c00 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
36c10 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
36c20 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
36c30 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
36c40 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
36c50 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
36c60 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
36c70 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
36c80 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
36c90 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
36ca0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
36cb0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
36cc0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
36cd0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
36ce0 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
36cf0 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
36d00 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
36d10 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
36d20 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
36d30 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
36d40 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36d50 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
36d60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
36d70 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
36d80 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
36d90 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
36da0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
36db0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
36dc0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
36dd0 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
36de0 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
36df0 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
36e00 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
36e10 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
36e20 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
36e30 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
36e40 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36e50 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
36e60 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
36e70 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
36e80 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
36e90 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
36ea0 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
36eb0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
36ec0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
36ed0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
36ee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
36ef0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36f00 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
36f10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36f20 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
36f30 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
36f40 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
36f50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
36f60 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
36f70 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
36f80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
36f90 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
36fa0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36fb0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
36fc0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
36fd0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
36fe0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
36ff0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
37000 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
37010 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
37020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37030 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
37040 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
37050 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
37060 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
37070 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
37080 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
37090 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
370a0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
370b0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
370c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
370d0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
370e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
370f0 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
37100 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
37110 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
37120 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
37130 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
37140 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
37150 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37160 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
37170 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
37180 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
37190 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
371a0 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
371b0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
371c0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
371d0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
371e0 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
371f0 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
37200 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
37210 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
37220 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
37230 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
37240 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
37250 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
37260 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37270 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
37280 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
37290 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
372a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
372b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
372c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
372d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
372e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
372f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
37300 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
37310 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
37320 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37330 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37340 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
37350 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
37360 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37370 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
37380 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
37390 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
373a0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
373b0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
373c0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
373d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
373e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
373f0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
37400 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  y)(void*).);.SQL
37410 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37420 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37430 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
37440 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
37450 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
37460 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
37470 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
37480 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
37490 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
374a0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
374b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
374c0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
374d0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
374e0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
374f0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
37500 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
37510 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
37520 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
37530 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
37540 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
37550 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37560 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
37570 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
37580 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
37590 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
375a0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
375b0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
375c0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
375d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
375e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
375f0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
37600 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
37610 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
37620 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
37630 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
37640 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
37650 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37660 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
37670 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
37680 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
37690 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
376a0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
376b0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
376c0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
376d0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
376e0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
376f0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
37700 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
37710 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
37720 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
37730 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37740 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
37750 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
37760 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37770 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
37780 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
37790 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
377a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
377b0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
377c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
377d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
377e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
377f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
37800 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
37810 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
37820 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
37830 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
37840 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
37850 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
37860 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
37870 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
37880 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
37890 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
378a0 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
378b0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
378c0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
378d0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
378e0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
378f0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
37900 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
37910 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
37920 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
37930 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
37940 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
37950 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
37960 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37970 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
37980 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37990 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
379a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
379b0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  on_v2()]..*/.SQL
379c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
379d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
379e0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
379f0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
37a00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
37a10 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
37a20 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
37a30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
37a40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
37a50 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
37a60 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37a70 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
37a80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
37a90 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
37aa0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
37ab0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
37ac0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
37ad0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
37ae0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
37af0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
37b00 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
37b10 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
37b20 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
37b30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
37b40 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
37b50 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
37b60 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
37b70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
37b80 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
37b90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37ba0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
37bb0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
37bc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
37bd0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
37be0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
37bf0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
37c00 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
37c10 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54   key */.);.SQLIT
37c20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37c30 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69  3_key_v2(.  sqli
37c40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37c50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37c60 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37c70 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37c80 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
37c90 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
37ca0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
37cb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
37cc0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
37cd0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
37ce0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
37cf0 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
37d00 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
37d10 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
37d20 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
37d30 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
37d40 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
37d50 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
37d60 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
37d70 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
37d80 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
37d90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
37da0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
37db0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
37dc0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
37dd0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
37de0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
37df0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37e00 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
37e10 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37e30 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
37e40 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
37e50 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37e60 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37e70 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37e80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37e90 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
37ea0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
37eb0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
37ec0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
37ed0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
37ee0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37ef0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
37f00 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
37f10 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
37f20 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
37f30 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37f40 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
37f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
37f60 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
37f70 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
37f80 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
37f90 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
37fa0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
37fb0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
37fc0 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
37fd0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
37fe0 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
37ff0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
38000 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
38010 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
38020 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
38030 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
38040 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
38050 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
38060 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
38070 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
38080 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
38090 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
380a0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
380b0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
380c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
380d0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
380e0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
380f0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
38100 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
38110 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
38120 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
38130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
38140 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
38150 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
38160 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
38170 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
38180 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
38190 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
381a0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
381b0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
381c0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
381d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
381e0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
381f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
38200 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
38210 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
38220 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
38230 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
38240 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
38250 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
38260 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
38270 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
38280 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
38290 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
382a0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
382b0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
382c0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
382d0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
382e0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
382f0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
38300 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
38310 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
38320 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
38330 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
38340 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
38350 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
38360 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
38370 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
38380 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
38390 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
383a0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
383b0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
383c0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
383d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
383e0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
383f0 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
38400 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
38410 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
38420 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
38430 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  aphs..*/.SQLITE_
38440 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38450 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
38460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
38470 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
38480 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
38490 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
384a0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
384b0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
384c0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
384d0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
384e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
384f0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
38500 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
38510 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
38520 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
38530 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
38540 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
38550 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
38560 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
38570 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
38580 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
38590 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
385a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
385b0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
385c0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
385d0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
385e0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
385f0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
38600 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
38610 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
38620 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38630 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
38640 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
38650 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
38660 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
38670 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
38680 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
38690 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
386a0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
386b0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
386c0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
386d0 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
386e0 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
386f0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
38700 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
38710 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
38720 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
38730 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
38740 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
38750 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
38760 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
38770 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
38780 73 20 76 61 72