System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 98a07da78f71b0275e8d9c510486877adc31dbee:


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 20 20 42  ersion 3.8.3.  B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20  y combining all 
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43  the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f   code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65   this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68   not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65  e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e  ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64  d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64   a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74   within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42  .  Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65  3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65   start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65   embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e  3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64  ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e  e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20  eeded.** if you 
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74  want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69  o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f  te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69  ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20  ng.** language. 
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65  The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61   "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73  nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65   also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69  parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68  only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69  e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e  brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a  e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69  MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49  fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51  VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61  LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a  I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a  ile 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 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
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 0a  ***************.
0740: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0750: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0760: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
0770: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
0780: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
0790: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
07a0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
07b0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
07c0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
07d0: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
07e0: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
07f0: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0800: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0810: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0820: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0830: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0840: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0850: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0860: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
0870: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
0880: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
0890: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
08a0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
08b0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
08c0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
08d0: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
08e0: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
08f0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0900: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0910: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0920: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0930: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0940: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0950: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0960: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
0970: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
0980: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
0990: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
09a0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
09b0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
09c0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
09d0: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
09e0: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
09f0: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0a00: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0a10: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0a20: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0a30: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0a40: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0a50: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0a60: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
0a70: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
0a80: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
0a90: 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70  re suppose to op
0aa0: 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  erate..**.** The
0ab0: 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69   name of this fi
0ac0: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75  le under configu
0ad0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
0ae0: 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69  t is "sqlite.h.i
0af0: 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66  n"..** The makef
0b00: 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d  ile makes some m
0b10: 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20  inor changes to 
0b20: 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20  this file (such 
0b30: 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  as inserting.** 
0b40: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  the version numb
0b50: 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20  er) and changes 
0b60: 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c  its name to "sql
0b70: 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61  ite3.h" as.** pa
0b80: 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20  rt of the build 
0b90: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e  process..*/.#ifn
0ba0: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0bb0: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0bc0: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0bd0: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0be0: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0bf0: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0c00: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0c10: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0c20: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
0c30: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20  rom C++..*/.#if 
0c40: 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  0.extern "C" {.#
0c50: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64  endif.../*.** Ad
0c60: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  d the ability to
0c70: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72   override 'exter
0c80: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  n'.*/.#ifndef SQ
0c90: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65  LITE_EXTERN.# de
0ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45  fine SQLITE_EXTE
0cb0: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66  RN extern.#endif
0cc0: 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  ..#ifndef SQLITE
0cd0: 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51  _API.# define SQ
0ce0: 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a  LITE_API.#endif.
0cf0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f  ../*.** These no
0d00: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75  -op macros are u
0d10: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20  sed in front of 
0d20: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61  interfaces to ma
0d30: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65  rk those.** inte
0d40: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72  rfaces as either
0d50: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65   deprecated or e
0d60: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65  xperimental.  Ne
0d70: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  w applications.*
0d80: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  * should not use
0d90: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65   deprecated inte
0da0: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72  rfaces - they ar
0db0: 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61  e support for ba
0dc0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
0dd0: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20  tibility only.  
0de0: 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74  Application writ
0df0: 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77  ers should be aw
0e00: 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65  are that.** expe
0e10: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
0e20: 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20  ces are subject 
0e30: 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69  to change in poi
0e40: 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  nt releases..**.
0e50: 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
0e60: 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20  used to resolve 
0e70: 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73  to various kinds
0e80: 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67   of compiler mag
0e90: 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64  ic that.** would
0ea0: 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e   generate warnin
0eb0: 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20  g messages when 
0ec0: 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20  they were used. 
0ed0: 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d   But that.** com
0ee0: 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65  piler magic ende
0ef0: 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20  d up generating 
0f00: 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66  such a flurry of
0f10: 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20   bug reports.** 
0f20: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b  that we have tak
0f30: 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e  en it all out an
0f40: 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75  d gone back to u
0f50: 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e  sing simple.** n
0f60: 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23  oop macros..*/.#
0f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
0f80: 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65  PRECATED.#define
0f90: 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
0fa0: 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  NTAL../*.** Ensu
0fb0: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
0fc0: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
0fd0: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
0fe0: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
0ff0: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
1000: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
1010: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
1020: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
1050: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1060: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
1070: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1080: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
1090: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
10a0: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  *.** ^(The [SQLI
10b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72  TE_VERSION] C pr
10c0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
10d0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e   in the sqlite3.
10e0: 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c  h header.** eval
10f0: 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e  uates to a strin
1100: 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69  g literal that i
1110: 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72  s the SQLite ver
1120: 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66  sion in the.** f
1130: 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68  ormat "X.Y.Z" wh
1140: 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a  ere X is the maj
1150: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
1160: 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a  r (always 3 for.
1170: 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20  ** SQLite3) and 
1180: 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  Y is the minor v
1190: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
11a0: 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61  d Z is the relea
11b0: 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20  se number.)^.** 
11c0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
11d0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20  RSION_NUMBER] C 
11e0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
11f0: 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61  ro resolves to a
1200: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74  n integer.** wit
1210: 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31  h the value (X*1
1220: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
1230: 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c  + Z) where X, Y,
1240: 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73   and Z are the s
1250: 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75  ame.** numbers u
1260: 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56  sed in [SQLITE_V
1270: 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68  ERSION].)^.** Th
1280: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
1290: 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20  _NUMBER for any 
12a0: 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66  given release of
12b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
12c0: 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74  o.** be larger t
12d0: 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20  han the release 
12e0: 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73  from which it is
12f0: 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65   derived.  Eithe
1300: 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68  r Y will.** be h
1310: 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64  eld constant and
1320: 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Z will be incre
1330: 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59  mented or else Y
1340: 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65   will be increme
1350: 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69  nted.** and Z wi
1360: 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a  ll be reset to z
1370: 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65  ero..**.** Since
1380: 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c   version 3.6.18,
1390: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
13a0: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
13b0: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
13c0: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
13d0: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
13e0: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
13f0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
1400: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
1410: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
1420: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
1430: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
1440: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
1450: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
1460: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1470: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1480: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1490: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
14a0: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
14b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
14c0: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
14d0: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
14e0: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
14f0: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1500: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
1510: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
1520: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
1530: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1540: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
1550: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
1560: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1570: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1580: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1590: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
15a0: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
15b0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
15c0: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
15d0: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 38 2e 33  ON        "3.8.3
15e0: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
15f0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1600: 33 30 30 38 30 30 33 0a 23 64 65 66 69 6e 65 20  3008003.#define 
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 20 20 20 20 20 20 22 32 30 31 34 2d 30 32 2d 30        "2014-02-0
1630: 33 20 31 33 3a 35 32 3a 30 33 20 65 38 31 36 64  3 13:52:03 e816d
1640: 64 39 32 34 36 31 39 64 62 35 66 37 36 36 64 65  d924619db5f766de
1650: 36 64 66 37 34 65 61 32 31 39 34 66 33 65 33 62  6df74ea2194f3e3b
1660: 35 33 38 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  538"../*.** CAPI
1670: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1680: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
1690: 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  umbers.** KEYWOR
16a0: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73  DS: sqlite3_vers
16b0: 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75  ion, sqlite3_sou
16c0: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rceid.**.** Thes
16d0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
16e0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
16f0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
1700: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1710: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
1720: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
1730: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
1740: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1750: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
1760: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1770: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1780: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1790: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
17a0: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
17b0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
17c0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
17d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
17e0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
17f0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
1800: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
1810: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
1820: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
1830: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
1840: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
1850: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
1860: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1870: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1880: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1890: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
18a0: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
18b0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18c0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
18d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
18e0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
18f0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
1900: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1910: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
1920: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
1930: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
1940: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
1950: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1960: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1970: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1980: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1990: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
19a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
19b0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
19c0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
19d0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
19e0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
19f0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
1a00: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
1a10: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
1a20: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
1a30: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
1a40: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1a50: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
1a60: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1a70: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1a80: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1a90: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1aa0: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1ab0: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
1ac0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
1ad0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
1ae0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
1af0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
1b00: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1b10: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
1b20: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
1b30: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
1b40: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1b50: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
1b60: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1b70: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1b80: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  rns .** a pointe
1b90: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  r to a string co
1ba0: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c  nstant whose val
1bb0: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  ue is the same a
1bc0: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  s the .** [SQLIT
1bd0: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1be0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1bf0: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  o..**.** See als
1c00: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  o: [sqlite_versi
1c10: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
1c20: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
1c30: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
1c40: 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33  nst char sqlite3
1c50: 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c  _version[] = SQL
1c60: 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c  ITE_VERSION;.SQL
1c70: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
1c80: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1c90: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51  ersion(void);.SQ
1ca0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
1cb0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75  har *sqlite3_sou
1cc0: 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c  rceid(void);.SQL
1cd0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1ce0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1cf0: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
1d00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1d10: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
1d20: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
1d30: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
1d40: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d50: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1d60: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
1d70: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
1d80: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
1d90: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
1da0: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
1db0: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
1dc0: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
1dd0: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
1de0: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
1df0: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
1e00: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
1e10: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
1e20: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
1e30: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
1e40: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1e50: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
1e60: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
1e70: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
1e80: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
1e90: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
1ea0: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
1eb0: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
1ec0: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
1ed0: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
1ee0: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
1ef0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
1f00: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1f10: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
1f20: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1f30: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
1f40: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
1f50: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
1f60: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
1f70: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
1f80: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1f90: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
1fa0: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
1fb0: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
1fc0: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
1fd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1fe0: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1ff0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
2000: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
2010: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
2020: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
2030: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
2040: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
2050: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
2060: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
2070: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
2080: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
2090: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
20a0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
20b0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
20c0: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
20d0: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
20e0: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
20f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
2100: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
2110: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2120: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
2130: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
2140: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
2150: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2160: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2170: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
2180: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
2190: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21a0: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
21b0: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
21c0: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
21d0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
21e0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
21f0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
2200: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
2210: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
2220: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
2230: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
2240: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
2250: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2260: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
2270: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
2280: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
2290: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
22a0: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
22b0: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
22c0: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
22d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
22e0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
22f0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
2300: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
2310: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
2320: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
2330: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
2340: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
2350: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
2360: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
2370: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
2380: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
2390: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
23a0: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
23b0: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
23c0: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
23d0: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
23e0: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
23f0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
2400: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
2410: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
2420: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
2430: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
2440: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
2450: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
2460: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
2470: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
2480: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
2490: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
24a0: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
24b0: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
24c0: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
24d0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
24e0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
24f0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
2500: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
2510: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
2520: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
2530: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
2540: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
2550: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2560: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
2570: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
2580: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
2590: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
25a0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
25b0: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
25c0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
25d0: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
25e0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
25f0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
2600: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2610: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2630: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
2640: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2650: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2660: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2670: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2680: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2690: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26a0: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
26b0: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
26c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
26d0: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
26e0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
26f0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
2700: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
2710: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  EX].  ^(The retu
2720: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
2730: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
2740: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
2750: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
2760: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
2770: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
2780: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
2790: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
27a0: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
27b0: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
27c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
27d0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
27e0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
27f0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
2800: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
2810: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
2820: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2830: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
2840: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
2850: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
2860: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2870: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2880: 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
2890: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  I int sqlite3_th
28a0: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
28b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28c0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
28d0: 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b  tion Handle.** K
28e0: 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61  EYWORDS: {databa
28f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b  se connection} {
2900: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2910: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68  ions}.**.** Each
2920: 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74   open SQLite dat
2930: 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65  abase is represe
2940: 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65  nted by a pointe
2950: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
2960: 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75   of.** the opaqu
2970: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
2980: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
2990: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
29a0: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
29b0: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
29c0: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
29d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
29e0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
29f0: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
2a00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2a10: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2a20: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
2a30: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  , and [sqlite3_c
2a40: 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  lose()].** and [
2a50: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2a60: 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74  ()] are its dest
2a70: 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20  ructors.  There 
2a80: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a  are many other.*
2a90: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  * interfaces (su
2aa0: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2ab0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2ac0: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ad0: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2ae0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2af0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2b00: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2b10: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
2b20: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
2b30: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
2b40: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2b50: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
2b60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
2b70: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2b80: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2b90: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2bb0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2bc0: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2bd0: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2be0: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2bf0: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2c00: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2c10: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2c20: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2c30: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2c40: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2c50: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2c60: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
2c70: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2c80: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2c90: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2ca0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2cb0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2cc0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2cd0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2ce0: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2cf0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2d00: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2d10: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2d20: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2d30: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
2d40: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
2d50: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
2d60: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
2d70: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2d80: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2d90: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2da0: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2db0: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2dc0: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2dd0: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2de0: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2df0: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2e00: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2e10: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
2e20: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
2e30: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2e40: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
2e50: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2e60: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2e70: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2e80: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2e90: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2ea0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2eb0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2ec0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ed0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2ee0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2ef0: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2f00: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2f10: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2f20: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
2f30: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
2f40: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
2f50: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
2f60: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
2f70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2f80: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2f90: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2fa0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2fb0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2fc0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2fd0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2fe0: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2ff0: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
3000: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
3010: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
3020: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
3030: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
3040: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
3050: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
3060: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
3070: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
3080: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
3090: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
30a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30b0: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
30c0: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66  destructors.** f
30d0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  or the [sqlite3]
30e0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c   object..** ^Cal
30f0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c  ls to sqlite3_cl
3100: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
3110: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74  3_close_v2() ret
3120: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
3130: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
3140: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63  ] object is succ
3150: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
3160: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
3170: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63  iated.** resourc
3180: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
3190: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
31a0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
31b0: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
31c0: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  ted with unfinal
31d0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a  ized prepared.**
31e0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75   statements or u
31f0: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
3200: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73  3_backup objects
3210: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
3220: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65  ose().** will le
3230: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
3240: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
3250: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
3260: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49  ITE_BUSY]..** ^I
3270: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  f sqlite3_close_
3280: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  v2() is called w
3290: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
32a0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32b0: 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e  nts.** and unfin
32c0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
32d0: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
32e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32f0: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3300: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3310: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3320: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3330: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3340: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3350: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
3360: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
3370: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
3380: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
3390: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
33a0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
33b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
33c0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
33d0: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
33e0: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
33f0: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3400: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3410: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3420: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3430: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3440: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3450: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
3460: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
3470: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
3480: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3490: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
34a0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
34b0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
34c0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
34d0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
34e0: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
34f0: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3500: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3510: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3520: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3530: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3540: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3550: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
3560: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
3570: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3580: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
3590: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
35b0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
35c0: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
35d0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
35e0: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
35f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3600: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3610: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
3620: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
3630: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
3640: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
3650: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3660: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3670: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3680: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3690: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
36a0: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
36b0: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
36c0: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
36d0: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
36e0: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
36f0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
3700: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
3710: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
3720: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
3730: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
3740: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3750: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3760: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3770: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3780: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3790: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
37a0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
37b0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
37c0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
37d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
37e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
37f0: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
3800: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
3810: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
3820: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
3830: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
3840: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
3850: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3860: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3870: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3880: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3890: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
38b0: 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  e(sqlite3*);.SQL
38c0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
38d0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c  te3_close_v2(sql
38e0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ite3*);../*.** T
38f0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
3900: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
3910: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
3920: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
3930: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
3940: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
3950: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
3960: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
3970: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
3980: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
3990: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
39a0: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
39b0: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
39c0: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
39d0: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
39e0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
39f0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
3a00: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
3a10: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20  s a convenience 
3a20: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
3a30: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
3a40: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
3a50: 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20  e3_step()], and 
3a60: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
3a70: 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c  e()],.** that al
3a80: 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74  lows an applicat
3a90: 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69  ion to run multi
3aa0: 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  ple statements o
3ab0: 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74  f SQL.** without
3ac0: 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61   having to use a
3ad0: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
3ae0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
3af0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
3b00: 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f  face runs zero o
3b10: 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63  r more UTF-8 enc
3b20: 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c  oded,.** semicol
3b30: 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20  on-separate SQL 
3b40: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3b50: 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61  d into its 2nd a
3b60: 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74  rgument,.** in t
3b70: 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68  he context of th
3b80: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3b90: 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69  ection] passed i
3ba0: 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20  n as its 1st.** 
3bb0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74  argument.  ^If t
3bc0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
3bd0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20  tion of the 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3bf0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3c00: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
3c10: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f  it is invoked fo
3c20: 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f  r each result ro
3c30: 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20  w.** coming out 
3c40: 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64  of the evaluated
3c50: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
3c60: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3c70: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3c80: 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61  3_exec() is rela
3c90: 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  yed through to t
3ca0: 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  he 1st argument 
3cb0: 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62  of each.** callb
3cc0: 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20  ack invocation. 
3cd0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3ce0: 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  k pointer to sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
3d00: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20  s NULL, then no 
3d10: 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72  callback is ever
3d20: 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73   invoked and res
3d30: 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20  ult rows are.** 
3d40: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
3d50: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
3d60: 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  rs while evaluat
3d70: 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74  ing the SQL stat
3d80: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
3d90: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3da0: 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75  ec(), then execu
3db0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72  tion of the curr
3dc0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74  ent statement st
3dd0: 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65  ops and.** subse
3de0: 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  quent statements
3df0: 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e   are skipped.  ^
3e00: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
3e10: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3e20: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  exec().** is not
3e30: 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65   NULL then any e
3e40: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20  rror message is 
3e50: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
3e60: 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ory obtained.** 
3e70: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
3e80: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73  lloc()] and pass
3e90: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
3ea0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3eb0: 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d  r..** To avoid m
3ec0: 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65  emory leaks, the
3ed0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
3ee0: 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  uld invoke [sqli
3ef0: 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f  te3_free()].** o
3f00: 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
3f10: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
3f20: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
3f30: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a   parameter of.**
3f40: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3f50: 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72  () after the err
3f60: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3f70: 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  g is no longer n
3f80: 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  eeded..** ^If th
3f90: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3fa0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3fb0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  ) is not NULL an
3fc0: 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
3fd0: 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  ccur, then sqlit
3fe0: 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74  e3_exec() sets t
3ff0: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74  he pointer in it
4000: 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 5th parameter 
4010: 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72  to.** NULL befor
4020: 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
4030: 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65  ** ^If an sqlite
4040: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
4050: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
4060: 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ro, the sqlite3_
4070: 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  exec().** routin
4080: 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
4090: 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69  _ABORT without i
40a0: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c  nvoking the call
40b0: 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a  back again and.*
40c0: 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e  * without runnin
40d0: 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  g any subsequent
40e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
40f0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20  .**.** ^The 2nd 
4100: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
4110: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
4120: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4130: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
4140: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
4150: 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68  the result.  ^Th
4160: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
4170: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
4180: 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  ec().** callback
4190: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
41a0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
41b0: 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20  ngs obtained as 
41c0: 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  if from.** [sqli
41d0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
41e0: 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68  )], one for each
41f0: 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e   column.  ^If an
4200: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a   element of a.**
4210: 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e   result row is N
4220: 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72  ULL then the cor
4230: 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e  responding strin
4240: 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  g pointer for th
4250: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
4260: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
4270: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
4280: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
4290: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c  nt to the.** sql
42a0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
42b0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
42c0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
42d0: 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61  strings where ea
42e0: 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72  ch.** entry repr
42f0: 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20  esents the name 
4300: 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  of corresponding
4310: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61   result column a
4320: 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
4330: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
4340: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
4350: 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61  * ^If the 2nd pa
4360: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4370: 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e  e3_exec() is a N
4380: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70  ULL pointer, a p
4390: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20  ointer.** to an 
43a0: 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72  empty string, or
43b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
43c0: 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68  contains only wh
43d0: 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20  itespace and/or 
43e0: 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73  .** SQL comments
43f0: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74  , then no SQL st
4400: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
4410: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
4420: 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f  atabase.** is no
4430: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
4440: 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a   Restrictions:.*
4450: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
4460: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
4470: 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  n must insure th
4480: 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  at the 1st param
4490: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
44a0: 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69  exec().**      i
44b0: 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70  s a valid and op
44c0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
44d0: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69  nection]..** <li
44e0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
44f0: 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  n must not close
4500: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
4510: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
4520: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
4530: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
4540: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
4550: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4560: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4570: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
4580: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4590: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
45a0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
45b0: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
45c0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
45d0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
45e0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
45f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
4600: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
4610: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
4620: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
4630: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4640: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4650: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4660: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4670: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4680: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t 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 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
46b0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
46c0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
46d0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
46e0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
46f0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4700: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
4710: 20 20 20 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 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4740: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4750: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4760: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4780: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4790: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
47a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
47b0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
47c0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
47d0: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
47e0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
47f0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
4800: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
4810: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
4820: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
4830: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
4840: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
4850: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
4860: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
4870: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
4880: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
4890: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
48a0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
48b0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
48c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
48d0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
48e0: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
48f0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
4900: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4910: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  es],.** [sqlite3
4920: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
4930: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  t()] [SQLITE_ROL
4940: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63  LBACK | result c
4950: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  odes]..*/.#defin
4960: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4970: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4980: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4990: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
49a0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
49b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
49c0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
49d0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
49e0: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
49f0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4a00: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4a10: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
4a20: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
4a30: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
4a40: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
4a50: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4a60: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4a70: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4a80: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4a90: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4aa0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4ab0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4ac0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4ad0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4ae0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4af0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4b00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b10: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
4b20: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
4b30: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
4b40: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4b60: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4b70: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4b80: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4ba0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4bb0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4bc0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4be0: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4bf0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4c00: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4c10: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
4c40: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
4c50: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4c60: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4c70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4c80: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4c90: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4ca0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4cb0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4cc0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4cd0: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4ce0: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4cf0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
4d00: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4d10: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4d20: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4d30: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4d40: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4d50: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4d60: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4d70: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4d80: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4d90: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4db0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4dc0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4dd0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4df0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4e00: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
4e10: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
4e20: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4e30: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4e40: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4e50: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4e60: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4e70: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4e80: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4e90: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4eb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4ec0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4ed0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4ee0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4ef0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4f00: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4f10: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4f20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4f30: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4f40: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4f50: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4f70: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4f80: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4f90: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4fa0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4fc0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4fd0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4fe0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4ff0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
5000: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
5010: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
5020: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5040: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
5050: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
5060: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
5070: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
5080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5090: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
50a0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
50b0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
50c0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
50d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
50e0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
50f0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
5100: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
5110: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5120: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
5130: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
5140: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
5150: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
5160: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
5170: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
5180: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
5190: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
51a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
51b0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
51c0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
51d0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
51e0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
51f0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
5200: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
5210: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
5220: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
5230: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
5240: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
5250: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  } {extended erro
5260: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
5270: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
5280: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78  result code} {ex
5290: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
52a0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  des}.**.** In it
52b0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
52c0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
52d0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
52e0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e  urn one of 26 in
52f0: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
5300: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
5310: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
5320: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
5330: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
5340: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
5350: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
5360: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
5370: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
5380: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
5390: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
53a0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
53b0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
53c0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
53d0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
53e0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
53f0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
5400: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
5410: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
5420: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
5430: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
5440: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
5450: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
5460: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
5470: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
5480: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
5490: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
54a0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
54b0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
54c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
54d0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
54e0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
54f0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
5500: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a  odes()] API..**.
5510: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
5520: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
5530: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
5540: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
5550: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
5560: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
5570: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5580: 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63 72 65  codes will incre
5590: 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  ase.** over time
55a0: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
55b0: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
55c0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
55d0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
55e0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
55f0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
5600: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
5610: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
5620: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
5630: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
5640: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
5650: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
5660: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
5670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5680: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
5690: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56a0: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
56b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56c0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
56d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56e0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5700: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
5710: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5720: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
5730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5740: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
5750: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5760: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
5770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5780: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
5790: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57a0: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
57b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
57c0: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
57d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
57e0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
57f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5800: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
5810: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5820: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5840: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5850: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5860: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5870: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5880: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5890: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
58a0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
58b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
58c0: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
58d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
58e0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
58f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
5900: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
5910: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5920: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
5930: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
5940: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5950: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5960: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5970: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5980: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5990: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
59a0: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
59c0: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
59d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
59e0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
59f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
5a00: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
5a10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5a20: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
5a40: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
5a50: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5a60: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
5a70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5a80: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5a90: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5aa0: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5ac0: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
5ad0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5ae0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5b00: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
5b10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5b20: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
5b30: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5b40: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
5b50: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5b60: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5b70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5b80: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5b90: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5ba0: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5bb0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5bc0: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5bd0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5be0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5bf0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5c00: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20  LETE_NOENT      
5c10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5c20: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (23<<8)).#define
5c30: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d   SQLITE_IOERR_MM
5c40: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AP              
5c50: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5c60: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (24<<8)).#define
5c70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45   SQLITE_IOERR_GE
5c80: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20  TTEMPPATH       
5c90: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5ca0: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (25<<8)).#define
5cb0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f   SQLITE_IOERR_CO
5cc0: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20  NVPATH          
5cd0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5ce0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (26<<8)).#define
5cf0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
5d00: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5d10: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5d20: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5d30: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5d40: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5d50: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5d60: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5d70: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5d80: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5d90: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
5da0: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
5db0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5dc0: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
5dd0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5de0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
5df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5e00: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
5e10: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5e20: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
5e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5e40: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5e50: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5e60: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5e70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5e80: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5e90: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5ea0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
5eb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ec0: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5ed0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5ee0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5ef0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5f00: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5f10: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5f20: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5f30: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5f40: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5f50: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5f60: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5f70: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5f80: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5f90: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5fa0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5fb0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5fc0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5fd0: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
5fe0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5ff0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
6010: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
6020: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
6030: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
6040: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6050: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
6060: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
6070: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
6080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6090: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
60a0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
60b0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
60c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
60d0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
60e0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
60f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
6100: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
6110: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6120: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
6130: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6140: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
6150: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6160: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
6170: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
6180: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
61a0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
61b0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
61c0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
61d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
61e0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
61f0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
6200: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
6210: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
6220: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6230: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
6240: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
6250: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
6260: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
6270: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
6280: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
6290: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
62a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
62b0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
62c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
62d0: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
62e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
62f0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
6300: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
6310: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
6320: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6330: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
6340: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
6350: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
6360: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
6370: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
6380: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
6390: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
63a0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
63b0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
63c0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
63d0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
63e0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
63f0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
6400: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
6410: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
6430: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
6440: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
6450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
6460: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6470: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
6480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6490: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
64a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
64b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
64c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
64d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
64e0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
64f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
6500: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6510: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6520: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6530: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
6540: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
6550: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6560: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6580: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
6590: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
65a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
65b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
65c0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
65d0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
65e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
65f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6600: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
6610: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
6620: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6640: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
6650: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
6660: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6670: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6690: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
66a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
66b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
66c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
66d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
66e0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
66f0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
6700: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6720: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
6730: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
6740: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6760: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
6770: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
6780: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
67a0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
67b0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
67c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
67d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
67e0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
67f0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
6800: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6810: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6820: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
6830: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6840: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6860: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6870: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6880: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
68a0: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
68b0: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
68c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
68d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
68e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
68f0: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
6900: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
6910: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6920: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6940: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6950: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6960: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6970: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6990: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
69a0: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
69b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
69c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
69d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
69e0: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
69f0: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
6a00: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6a10: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
6a20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a30: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6a40: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6a50: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6a60: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6a70: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6a80: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6a90: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6aa0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6ab0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6ac0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6ad0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6ae0: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6af0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6b00: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6b10: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6b20: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6b30: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6b40: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6b50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6b60: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6b70: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6b80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6ba0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6bb0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6bc0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6bd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6be0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6bf0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6c00: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6c10: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6c20: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6c30: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6c40: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6c50: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6c60: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6c70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6c80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6c90: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6ca0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6cb0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6cc0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6cd0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6ce0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6cf0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6d00: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6d10: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6d20: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6d30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6d40: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6d50: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6d60: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6d70: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6d80: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6d90: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6da0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6db0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6dc0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6dd0: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6de0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6df0: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6e00: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6e10: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6e20: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6e30: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6e40: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6e50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6e60: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6e70: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6e80: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6e90: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6ea0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6eb0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6ec0: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6ed0: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6ee0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6ef0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
6f00: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
6f10: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6f20: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6f30: 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64 65 66 69  n open..*/.#defi
6f40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f50: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6f60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6f70: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6f80: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6fa0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6fb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6fc0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6fd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6fe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ff0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
7000: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7010: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
7020: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7030: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
7040: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
7050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7060: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
7070: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7080: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
7090: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70a0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
70b0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
70c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70d0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
70e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
70f0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
7100: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
7110: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
7120: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
7130: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7140: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
7150: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
7160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7170: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7180: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
7190: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
71a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
71b0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
71c0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
71d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71e0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
71f0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
7200: 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  01000../*.** CAP
7210: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
7220: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
7230: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
7240: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
7250: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7260: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
7270: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
7280: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
7290: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
72a0: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
72b0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
72c0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
72d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72e0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
72f0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
7300: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7310: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
7320: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
7330: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
7340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7350: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
7360: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7370: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7380: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
7390: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
73a0: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
73b0: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
73c0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
73d0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
73e0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
73f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7400: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
7410: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
7420: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
7430: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7440: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7450: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7460: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7470: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7480: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7490: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
74a0: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
74b0: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
74c0: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
74d0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
74e0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
74f0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
7500: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
7510: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
7520: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7530: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7540: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7550: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7560: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7570: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7580: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7590: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
75a0: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
75b0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
75c0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
75d0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
75e0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
75f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7600: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7610: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
7620: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
7630: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7640: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7650: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7660: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7670: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7680: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7690: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
76a0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
76b0: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
76c0: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
76d0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
76e0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
76f0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
7700: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7710: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7720: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
7730: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7740: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7750: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7760: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7770: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7780: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7790: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
77a0: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
77b0: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
77c0: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
77d0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
77e0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
77f0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
7800: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
7810: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7820: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
7830: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7840: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7850: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7860: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7870: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7880: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7890: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
78a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
78b0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
78c0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
78d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
78e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
78f0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
7900: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
7910: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
7920: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7930: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7940: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7950: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7960: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7970: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7980: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7990: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
79a0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
79b0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
79c0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
79d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
79e0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
79f0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
7a00: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
7a10: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7a20: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
7a30: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7a40: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7a50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7a60: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a70: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7a80: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7a90: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7aa0: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7ab0: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
7ac0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7ae0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
7af0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7b00: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7b10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7b20: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7b30: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7b40: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7b50: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7b60: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7b70: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7b80: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7b90: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7ba0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7bb0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7bc0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
7bd0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7be0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7bf0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7c00: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7c10: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7c20: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7c30: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7c40: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7c50: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7c60: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7c70: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7c80: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7c90: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7ca0: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7cb0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7cc0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
7cd0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7ce0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7cf0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7d00: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7d10: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7d20: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7d30: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7d40: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7d50: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7d60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7d70: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7d80: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7d90: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7da0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7db0: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7dc0: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
7dd0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7de0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7df0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7e00: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7e10: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7e20: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7e30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7e40: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7e50: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7e60: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7e70: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7e80: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7e90: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7ea0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7eb0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7ec0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7ed0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7ee0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7ef0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7f00: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7f10: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7f20: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7f30: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7f40: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7f50: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7f60: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7f70: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7f80: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7f90: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7fa0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7fb0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7fc0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7fd0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7fe0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7ff0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
8000: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
8010: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
8020: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8030: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8040: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8050: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8060: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8070: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
8080: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8090: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
80a0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
80b0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
80c0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
80d0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
80e0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
80f0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
8100: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
8110: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
8120: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
8130: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
8140: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
8150: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
8160: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
8170: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
8180: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
8190: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
81a0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
81b0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
81c0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
81d0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
81e0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
81f0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
8200: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
8210: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
8220: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
8230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
8240: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
8250: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
8260: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
8270: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8280: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
8290: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
82a0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
82b0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
82c0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
82d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
82e0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
82f0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
8300: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
8310: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
8320: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
8330: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
8340: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
8350: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
8360: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
8370: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
8380: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
8390: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
83a0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
83b0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
83c0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
83d0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
83e0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
83f0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
8400: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
8410: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
8420: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
8430: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8440: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8450: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8460: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8470: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8480: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8490: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
84a0: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
84b0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
84c0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
84d0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
84e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
84f0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8500: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8510: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8520: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8530: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8540: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8560: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8570: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8580: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8590: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
85a0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
85b0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
85c0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
85d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
85e0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
85f0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8600: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8610: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8620: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8630: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8640: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8650: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8660: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8670: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8680: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8690: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
86a0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
86b0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
86c0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
86d0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
86e0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
86f0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8700: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8710: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8720: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8730: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8740: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8750: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8760: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8770: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8780: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8790: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
87a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
87e0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8800: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8820: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8830: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8840: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8850: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8860: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
8870: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8880: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8890: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
88a0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
88b0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
88c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
88d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
88e0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
88f0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
8900: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8910: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8920: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8930: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8940: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8950: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8960: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8990: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
89a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
89b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
89c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
89d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
89e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
89f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8a00: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8a10: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8a20: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8a30: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8a40: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8a50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a60: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8a70: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8a80: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8a90: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8aa0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8ab0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8ac0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
8ad0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
8ae0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
8af0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
8b00: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
8b10: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
8b20: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8b30: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8b40: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8b50: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8b60: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8b70: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8b80: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8b90: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8ba0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8bb0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8bc0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
8bd0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8be0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
8bf0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
8c00: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
8c10: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
8c20: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8c30: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8c40: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8c50: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8c60: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8c70: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8c80: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8c90: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8ca0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8cb0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8cc0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8cd0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8ce0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
8cf0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
8d10: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
8d20: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8d30: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8d40: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8d50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8d70: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8d80: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8d90: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8da0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8dc0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
8dd0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
8de0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8df0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8e00: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
8e10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8e20: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8e30: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8e40: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8e50: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e60: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8e70: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8e80: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8e90: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8ea0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8eb0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8ec0: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
8ed0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
8ee0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
8ef0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
8f00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
8f10: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f20: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8f30: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8f40: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8f50: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8f60: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8f70: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8f80: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8f90: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8fa0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8fb0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8fc0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
8fd0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
8fe0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8ff0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
9000: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
9010: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
9020: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
9030: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
9040: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
9050: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
9060: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
9070: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
9080: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
9090: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
90a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
90b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
90c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
90d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
90e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
90f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
9100: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
9110: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
9120: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
9130: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
9140: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
9150: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
9160: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
9170: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
9180: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
9190: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
91a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
91b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
91c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
91d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
91e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
91f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
9200: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
9210: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
9220: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
9230: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
9240: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
9250: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
9260: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
9270: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
9280: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
9290: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
92a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
92b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
92c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
92d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
92e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
92f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
9300: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
9310: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
9320: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
9330: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
9340: 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ined..** <ul>.**
9350: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9360: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
9370: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9380: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
9390: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
93a0: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
93b0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
93c0: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
93d0: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
93e0: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
93f0: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
9400: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
9410: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
9420: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
9430: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
9440: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
9450: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
9460: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
9470: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
9480: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
9490: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
94a0: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
94b0: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
94c0: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
94d0: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
94e0: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
94f0: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
9500: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9510: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
9520: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9530: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
9540: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9550: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
9560: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
9570: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
9580: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9590: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
95a0: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
95b0: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
95c0: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
95d0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
95e0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
95f0: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9600: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9610: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9620: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9630: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9640: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9650: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9660: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9670: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
9680: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
9690: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
96a0: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
96b0: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
96c0: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
96d0: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
96e0: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
96f0: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9710: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9720: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9730: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9740: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9750: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9760: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9770: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9780: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9790: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
97a0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
97b0: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20  ction.  See the 
97c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
97d0: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e  ntrol()] documen
97e0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64  tation for.** ad
97f0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
9800: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
9810: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9820: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9830: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9840: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9850: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9860: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9870: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9880: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9890: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
98a0: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
98b0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
98c0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
98d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
98e0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
98f0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9900: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9910: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9920: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9930: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9940: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9950: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9960: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9970: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9980: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9990: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
99a0: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
99b0: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
99c0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
99d0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
99e0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
99f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9a00: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9a10: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9a20: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9a30: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9a40: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9a50: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9a60: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9a70: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9a80: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9a90: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
9aa0: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
9ab0: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
9ac0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
9ad0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9ae0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9af0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9b00: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9b10: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9b20: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9b30: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9b40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9b50: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9b60: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9b70: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9b80: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9b90: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9ba0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9bb0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9bc0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9bd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9be0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9bf0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9c00: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9c10: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9c20: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9c30: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9c40: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9c50: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9c60: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9c70: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9c80: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9c90: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9ca0: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9cb0: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9cc0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9cd0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9ce0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9cf0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9d00: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9d10: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9d20: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9d30: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9d40: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9d50: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9d60: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9d70: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9d80: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9d90: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9da0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9db0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9dc0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9dd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9de0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9df0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9e00: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9e10: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9e20: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9e30: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9e40: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9e50: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9e60: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9e70: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9e80: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9e90: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9ea0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9eb0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9ec0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9ed0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9ee0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9ef0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9f00: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9f10: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9f20: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9f30: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9f40: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9f50: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9f60: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9f70: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
9f80: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
9f90: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
9fa0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9fb0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9fc0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9fd0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9fe0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9ff0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a000: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a010: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a020: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a030: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a040: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a050: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a060: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a070: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a080: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a090: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a0a0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a0b0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a0c0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
a0d0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
a0e0: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
a0f0: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
a100: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
a110: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
a120: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
a130: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
a140: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
a150: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
a160: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
a170: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
a180: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
a190: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
a1a0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
a1b0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
a1c0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
a1d0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
a1e0: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
a1f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a200: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
a210: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
a220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
a230: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
a240: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
a250: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
a260: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
a270: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
a280: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
a290: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
a2a0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
a2b0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
a2c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
a2d0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
a2e0: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
a2f0: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
a300: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
a310: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
a320: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
a330: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
a340: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
a350: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
a360: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
a370: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
a380: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
a390: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
a3a0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
a3b0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
a3c0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
a3d0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
a3e0: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
a3f0: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
a400: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a410: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
a420: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
a430: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
a440: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
a450: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
a460: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
a470: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
a480: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
a490: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
a4a0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a4b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a4c0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a4d0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a4e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a4f0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a500: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a510: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
a520: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
a530: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
a540: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
a550: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a560: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a570: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a580: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a590: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
a5a0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
a5b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a5c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a5d0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
a5e0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a5f0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a600: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a610: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a620: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a630: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
a640: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
a650: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
a660: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
a670: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
a680: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
a690: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
a6a0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
a6b0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
a6c0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
a6d0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
a6e0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a6f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a700: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a710: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a720: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a730: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a740: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a750: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
a760: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a770: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
a780: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
a790: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a7a0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a7b0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a7c0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a7d0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
a7e0: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
a7f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a800: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a810: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a830: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a840: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a850: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
a860: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
a870: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
a880: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
a890: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
a8a0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
a8b0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
a8c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a8d0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
a8e0: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
a8f0: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
a900: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
a910: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
a920: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
a930: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a940: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
a950: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a960: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
a970: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
a980: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
a990: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
a9a0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
a9b0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
a9c0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
a9d0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
a9e0: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
a9f0: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
aa00: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
aa10: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
aa20: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
aa30: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
aa40: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
aa50: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
aa60: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
aa70: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
aa80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
aa90: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
aaa0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
aab0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
aac0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
aad0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
aae0: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
aaf0: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
ab00: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
ab10: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
ab20: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
ab30: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
ab40: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
ab50: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
ab60: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
ab70: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
ab80: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
ab90: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
aba0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
abb0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
abc0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
abd0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
abe0: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
abf0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
ac00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac10: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
ac20: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
ac30: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
ac40: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
ac50: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
ac60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ac70: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
ac80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
ac90: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
aca0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
acb0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
acc0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
acd0: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
ace0: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
acf0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
ad00: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ad10: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
ad20: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
ad30: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
ad40: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
ad50: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
ad60: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
ad70: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
ad80: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
ad90: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
ada0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
adb0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
adc0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
add0: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
ade0: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
adf0: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
ae00: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
ae10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ae20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
ae30: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
ae40: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
ae50: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
ae60: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
ae70: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
ae80: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
ae90: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
aea0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
aeb0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
aec0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
aed0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
aee0: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
aef0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
af00: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
af10: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
af20: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
af30: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
af40: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
af50: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
af60: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
af70: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
af80: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
af90: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
afa0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
afb0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
afc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
afd0: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
afe0: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
aff0: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
b000: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
b010: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
b020: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
b030: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
b040: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
b050: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
b060: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b070: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b080: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
b090: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
b0a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
b0b0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
b0c0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
b0d0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
b0e0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
b0f0: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
b100: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
b110: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
b120: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
b130: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
b140: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
b150: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b160: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
b170: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
b180: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
b190: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
b1a0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
b1b0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
b1c0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
b1d0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
b1e0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
b1f0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b200: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
b210: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
b220: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b230: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
b240: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
b250: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
b260: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b270: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
b280: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
b290: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
b2a0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
b2b0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
b2c0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
b2d0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
b2e0: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
b2f0: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
b300: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
b310: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
b320: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
b330: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
b340: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
b350: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
b360: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
b370: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
b380: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
b390: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
b3a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
b3b0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
b3c0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
b3d0: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
b3e0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
b3f0: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
b400: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
b410: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
b420: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
b430: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
b440: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
b450: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
b460: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
b470: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
b480: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
b490: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
b4a0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
b4b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b4c0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
b4d0: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
b4e0: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
b4f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b500: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
b510: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
b520: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
b530: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
b540: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
b550: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
b560: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
b570: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
b580: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
b590: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
b5a0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
b5b0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
b5c0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
b5d0: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
b5e0: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
b5f0: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
b600: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
b610: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
b620: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
b630: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
b640: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
b650: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
b660: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
b670: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
b680: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
b690: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
b6a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b6b0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
b6c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b6d0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
b6e0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b6f0: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
b700: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
b710: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b720: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
b730: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
b740: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
b750: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b760: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
b770: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
b780: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
b790: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
b7a0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b7b0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
b7c0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
b7d0: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
b7e0: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
b7f0: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
b800: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
b810: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
b820: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
b830: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
b840: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
b850: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
b860: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
b870: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
b880: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
b890: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
b8a0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
b8b0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
b8c0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
b8d0: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
b8e0: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
b8f0: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
b900: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b910: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
b920: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b930: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
b940: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
b950: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
b960: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
b970: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
b980: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
b990: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
b9a0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
b9b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b9c0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
b9d0: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
b9e0: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
b9f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
ba00: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
ba10: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
ba20: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
ba30: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
ba40: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
ba50: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
ba60: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
ba70: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
ba80: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
ba90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
baa0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
bab0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bac0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bad0: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
baf0: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
bb00: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
bb10: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
bb20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
bb30: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
bb40: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
bb50: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
bb60: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
bb70: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
bb80: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
bb90: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
bba0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
bbb0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
bbc0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
bbd0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
bbe0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
bbf0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
bc00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
bc10: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
bc20: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
bc30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
bc40: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
bc50: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
bc60: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
bc70: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
bc80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bc90: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
bca0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
bcb0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
bcc0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
bcd0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
bce0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
bcf0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
bd00: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
bd10: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
bd20: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
bd30: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
bd40: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
bd50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
bd60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
bd70: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
bd80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
bda0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
bdb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bdc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
bdd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
bde0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bdf0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
be00: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
be10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
be20: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
be30: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
be40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
be50: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
be60: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
be70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
be80: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
be90: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
bea0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
beb0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
bec0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
bed0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
bee0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
bef0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
bf00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
bf10: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
bf20: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
bf30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
bf40: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
bf50: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
bf60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
bf70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bf80: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
bf90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
bfa0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
bfb0: 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    22../*.** CAPI
bfc0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
bfd0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
bfe0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
bff0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
c000: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c010: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
c020: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
c030: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
c040: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
c050: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
c060: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
c070: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
c080: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
c090: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
c0a0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
c0b0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
c0c0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
c0d0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
c0e0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
c0f0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
c100: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
c110: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
c120: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
c130: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
c140: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
c150: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
c160: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
c170: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
c180: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
c190: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
c1a0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
c1b0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
c1c0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
c1d0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
c1e0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
c1f0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
c200: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
c210: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
c220: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
c230: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
c240: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
c250: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
c260: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
c270: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
c280: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
c290: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
c2a0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
c2b0: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
c2c0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
c2d0: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
c2e0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
c2f0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
c300: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
c310: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
c320: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
c330: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
c340: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
c350: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c360: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
c370: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
c380: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
c390: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
c3a0: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
c3b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c3c0: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
c3d0: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
c3e0: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
c3f0: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
c400: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
c410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
c420: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
c430: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
c440: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
c450: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
c460: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
c470: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
c480: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
c490: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
c4a0: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
c4b0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
c4c0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
c4d0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
c4e0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
c4f0: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
c500: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
c510: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
c520: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
c530: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
c540: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
c550: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c560: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
c570: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
c580: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
c590: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
c5a0: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
c5b0: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
c5c0: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
c5d0: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
c5e0: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
c5f0: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
c600: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
c610: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c620: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
c630: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
c640: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
c650: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
c660: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
c670: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
c680: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
c690: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
c6a0: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
c6b0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
c6c0: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
c6d0: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
c6e0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c6f0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
c700: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
c710: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
c720: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
c730: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
c740: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
c750: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
c760: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
c770: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
c780: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
c790: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
c7a0: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
c7b0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
c7c0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c7d0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
c7e0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
c7f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
c800: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
c810: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
c820: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
c830: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
c840: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
c850: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
c860: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
c870: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
c880: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
c890: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
c8a0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
c8b0: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
c8c0: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
c8d0: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
c8e0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
c8f0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
c900: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
c910: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
c920: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
c930: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
c940: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
c950: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
c960: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
c970: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
c980: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
c990: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
c9a0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
c9b0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
c9c0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
c9d0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
c9e0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
c9f0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
ca00: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
ca10: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
ca20: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
ca30: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
ca40: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
ca50: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
ca60: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
ca70: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
ca80: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
ca90: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
caa0: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
cab0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
cac0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
cad0: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
cae0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
caf0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
cb00: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
cb10: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
cb20: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
cb30: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
cb40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
cb50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
cb60: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
cb70: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
cb80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
cb90: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
cba0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
cbb0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
cbc0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
cbd0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
cbe0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
cbf0: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
cc00: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
cc10: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
cc20: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
cc30: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
cc40: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
cc50: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
cc60: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
cc70: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
cc80: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
cc90: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
cca0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
ccb0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
ccc0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
ccd0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
cce0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
ccf0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
cd00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
cd10: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
cd20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
cd30: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
cd40: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cd50: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
cd60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
cd70: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
cd80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cd90: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
cda0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
cdb0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
cdc0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
cdd0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
cde0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
cdf0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
ce00: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
ce10: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
ce20: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
ce30: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
ce40: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
ce50: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
ce60: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
ce70: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
ce80: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
ce90: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
cea0: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
ceb0: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
cec0: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
ced0: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
cee0: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
cef0: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
cf00: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
cf10: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
cf20: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
cf30: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
cf40: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
cf50: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
cf60: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
cf70: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
cf80: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
cf90: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
cfa0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
cfb0: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
cfc0: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
cfd0: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
cfe0: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
cff0: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
d000: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
d010: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
d020: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
d030: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
d040: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
d050: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
d060: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
d070: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d080: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
d090: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d0a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
d0b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
d0c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
d0d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d0e0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
d0f0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
d100: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
d110: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
d120: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
d130: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d140: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
d150: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
d160: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
d170: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
d180: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
d190: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
d1a0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
d1b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
d1c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
d1d0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
d1e0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
d1f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
d200: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
d210: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
d220: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
d230: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
d240: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
d250: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
d260: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
d270: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
d280: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
d290: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
d2a0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
d2b0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
d2c0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
d2d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
d2e0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
d2f0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
d300: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
d310: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
d320: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
d330: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
d340: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
d350: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
d360: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
d370: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
d380: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
d390: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
d3a0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
d3b0: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
d3c0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
d3d0: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
d3e0: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
d3f0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
d400: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
d410: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
d420: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
d430: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
d440: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
d450: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
d460: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
d470: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
d480: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
d490: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
d4a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
d4b0: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
d4c0: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
d4d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
d4e0: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
d4f0: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
d500: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
d510: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
d520: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
d530: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
d540: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
d550: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
d560: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
d570: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
d580: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
d590: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
d5a0: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
d5b0: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
d5c0: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
d5d0: 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
d5e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d5f0: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
d600: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
d610: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
d620: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
d630: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
d640: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d650: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
d660: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
d670: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
d680: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
d690: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d6a0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
d6b0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d6c0: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
d6d0: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
d6e0: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
d6f0: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
d700: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d710: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
d720: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
d730: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
d740: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
d750: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
d760: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
d770: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
d780: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
d790: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
d7a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
d7b0: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
d7c0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d7d0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
d7e0: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
d7f0: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
d800: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
d810: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
d820: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
d830: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
d840: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
d850: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
d860: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
d870: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
d880: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
d890: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
d8a0: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
d8b0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
d8c0: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
d8d0: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
d8e0: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
d8f0: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
d900: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
d910: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
d920: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
d930: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
d940: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
d950: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
d960: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
d970: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
d980: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
d990: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
d9a0: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
d9b0: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
d9c0: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
d9d0: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
d9e0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
d9f0: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
da00: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
da10: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
da20: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
da30: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
da40: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
da50: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
da60: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
da70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
da80: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
da90: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
daa0: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
dab0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
dac0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
dad0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
dae0: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
daf0: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
db00: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
db10: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
db20: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
db30: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
db40: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
db50: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
db60: 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
db70: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
db80: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
db90: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
dba0: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
dbb0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
dbc0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
dbd0: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
dbe0: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
dbf0: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
dc00: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
dc10: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
dc20: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
dc30: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
dc40: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
dc50: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
dc60: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
dc70: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
dc80: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
dc90: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
dca0: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
dcb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
dcc0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
dcd0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
dce0: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
dcf0: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
dd00: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
dd10: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
dd20: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
dd30: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
dd40: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
dd50: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
dd60: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
dd70: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
dd80: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
dd90: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
dda0: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
ddb0: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
ddc0: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
ddd0: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
dde0: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
ddf0: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
de00: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
de10: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
de20: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
de30: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
de40: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
de50: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
de60: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
de70: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
de80: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
de90: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
dea0: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
deb0: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
dec0: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
ded0: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
dee0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
def0: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
df00: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
df10: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
df20: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
df30: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
df40: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
df50: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
df60: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
df70: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
df80: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
df90: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
dfa0: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
dfb0: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
dfc0: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
dfd0: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
dfe0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
dff0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
e000: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
e010: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
e020: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
e030: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
e040: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
e050: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
e060: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
e070: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
e080: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
e090: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
e0a0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
e0b0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
e0c0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
e0d0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
e0e0: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
e0f0: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
e100: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
e110: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
e120: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
e130: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
e140: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
e150: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
e160: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
e170: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
e180: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
e190: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
e1a0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
e1b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
e1c0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
e1d0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
e1e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e1f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
e200: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
e210: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
e220: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
e230: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
e240: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
e250: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e260: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
e270: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
e280: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
e290: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e2a0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
e2b0: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
e2c0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
e2d0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
e2e0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e2f0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e300: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
e310: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
e320: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
e330: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e340: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
e350: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
e360: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e370: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
e380: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
e390: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
e3a0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
e3b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
e3c0: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
e3d0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
e3e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
e3f0: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
e400: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
e410: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
e420: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
e430: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
e440: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e450: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
e460: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
e470: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
e480: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
e490: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
e4a0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
e4b0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
e4c0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
e4d0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
e4e0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
e4f0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e500: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
e510: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
e520: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
e530: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
e540: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
e550: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
e560: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
e570: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
e580: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
e590: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e5a0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e5b0: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
e5c0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e5d0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
e5e0: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
e5f0: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
e600: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
e610: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
e620: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e630: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e640: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
e650: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
e660: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e670: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
e680: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e690: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e6a0: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
e6b0: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
e6c0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e6d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e6e0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
e6f0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e700: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e710: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
e720: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
e730: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e740: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
e750: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
e760: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
e770: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
e780: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
e790: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
e7a0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
e7b0: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
e7c0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e7d0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
e7e0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e7f0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e800: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
e810: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
e820: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e830: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e840: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
e850: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
e860: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
e870: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
e880: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
e890: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
e8a0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
e8b0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e8c0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
e8d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e8e0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
e8f0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e900: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
e910: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e920: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
e930: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e940: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e950: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
e960: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
e970: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
e980: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
e990: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
e9a0: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
e9b0: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
e9c0: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
e9d0: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
e9e0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e9f0: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
ea00: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
ea10: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
ea20: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
ea30: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
ea40: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
ea50: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
ea60: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
ea70: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
ea80: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
ea90: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
eaa0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
eab0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
eac0: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
ead0: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
eae0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
eaf0: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
eb00: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
eb10: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
eb20: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
eb30: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
eb40: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
eb50: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
eb60: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
eb70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
eb80: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
eb90: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
eba0: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
ebb0: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
ebc0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
ebd0: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
ebe0: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
ebf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
ec00: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
ec10: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
ec20: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
ec30: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
ec40: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
ec50: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
ec60: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
ec70: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
ec80: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
ec90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
eca0: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
ecb0: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
ecc0: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
ecd0: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
ece0: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
ecf0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
ed00: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ed10: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
ed20: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
ed30: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
ed40: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
ed50: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
ed60: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
ed70: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
ed80: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
ed90: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
eda0: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
edb0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
edc0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
edd0: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
ede0: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
edf0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
ee00: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
ee10: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
ee20: 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
ee30: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
ee40: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
ee50: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
ee60: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
ee70: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
ee80: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
ee90: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
eea0: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
eeb0: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
eec0: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
eed0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
eee0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
eef0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
ef00: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
ef10: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
ef20: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
ef30: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
ef40: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
ef50: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
ef60: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
ef70: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
ef80: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
ef90: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
efa0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
efb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
efc0: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
efd0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
efe0: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
eff0: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
f000: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
f010: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
f020: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
f030: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
f040: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
f050: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
f060: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
f070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f080: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
f090: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f0a0: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
f0b0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
f0c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
f0d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0e0: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
f0f0: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
f100: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
f110: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f120: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
f130: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
f140: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
f150: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
f160: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f170: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
f180: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
f190: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
f1a0: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
f1b0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
f1c0: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
f1d0: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
f1e0: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
f1f0: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
f200: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
f210: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
f220: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
f230: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
f240: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f250: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f260: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
f270: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
f280: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
f290: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
f2a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
f2b0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
f2c0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
f2d0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
f2e0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
f2f0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
f300: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
f310: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
f320: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
f330: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f340: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
f350: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
f360: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
f370: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
f380: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
f390: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
f3a0: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
f3b0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f3c0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f3d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
f3e0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
f3f0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
f400: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
f410: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
f420: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
f430: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
f440: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
f450: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
f460: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
f470: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
f480: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
f490: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
f4a0: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
f4b0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
f4c0: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
f4d0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
f4e0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f4f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
f500: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
f510: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
f520: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
f530: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
f540: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f550: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
f560: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
f570: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
f580: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
f590: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f5a0: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
f5b0: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
f5c0: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
f5d0: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
f5e0: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
f5f0: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
f600: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
f610: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
f620: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
f630: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
f640: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
f650: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
f660: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
f670: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
f680: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
f690: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f6a0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
f6b0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f6c0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f6d0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
f6e0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f6f0: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
f700: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
f710: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f720: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
f730: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
f740: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
f750: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
f760: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
f770: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
f780: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
f790: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
f7a0: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
f7b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
f7c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f7d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f7e0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
f7f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
f800: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
f810: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f820: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
f830: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
f840: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
f850: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
f860: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f870: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
f880: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
f890: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
f8a0: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
f8b0: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
f8c0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
f8d0: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
f8e0: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
f8f0: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
f900: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
f910: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
f920: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
f930: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
f940: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
f950: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f960: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
f970: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
f980: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f990: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
f9a0: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
f9b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f9c0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
f9d0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
f9e0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
f9f0: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
fa00: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
fa10: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
fa20: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
fa30: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
fa40: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
fa50: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
fa60: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
fa70: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
fa80: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
fa90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
faa0: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
fab0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
fac0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
fad0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
fae0: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
faf0: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
fb00: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
fb10: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
fb20: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
fb30: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
fb40: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
fb50: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
fb60: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
fb70: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
fb80: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
fb90: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
fba0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
fbb0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
fbc0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
fbd0: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
fbe0: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
fbf0: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
fc00: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
fc10: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
fc20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fc30: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
fc40: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
fc50: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fc60: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
fc70: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
fc80: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
fc90: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
fca0: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
fcb0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
fcc0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
fcd0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
fce0: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
fcf0: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
fd00: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
fd10: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
fd20: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
fd30: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
fd40: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
fd50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
fd60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
fd70: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
fd80: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
fd90: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
fda0: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
fdb0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
fdc0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
fdd0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
fde0: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
fdf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe00: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
fe10: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
fe20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe30: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
fe40: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
fe50: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
fe60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fe70: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
fe80: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
fe90: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
fea0: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
feb0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
fec0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
fed0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
fee0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fef0: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
ff00: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
ff10: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
ff20: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
ff30: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
ff40: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
ff50: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
ff60: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
ff70: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
ff80: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
ff90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
ffa0: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
ffb0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
ffc0: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
ffd0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
ffe0: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
fff0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
10000 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
10010 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
10020 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
10030 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
10040 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
10050 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10060 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
10070 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
10080 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
10090 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
100a0 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
100b0 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ure..*/.SQLITE_A
100c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  PI int sqlite3_i
100d0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
100e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
100f0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10100 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
10110 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
10120 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
10130 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
10140 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
10150 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10160 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
10170 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10180 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10190 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
101a0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
101b0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
101c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
101d0 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
101e0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
101f0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10200 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10210 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10220 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
10230 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10240 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10250 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10260 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10270 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10280 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10290 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
102a0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
102b0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
102c0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
102d0 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
102e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
102f0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10300 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10310 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
10320 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
10330 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10340 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10350 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10360 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10370 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10380 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10390 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
103a0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
103b0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
103c0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
103d0 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
103e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
103f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
10400 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
10410 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
10420 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
10430 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
10440 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10450 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
10460 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10470 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
10480 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
10490 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
104a0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
104b0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
104c0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
104d0 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
104e0 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
104f0 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
10500 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
10510 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
10520 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
10530 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10540 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
10550 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10560 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10570 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
10580 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
10590 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
105a0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
105b0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
105c0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
105d0 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
105e0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
105f0 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
10600 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
10610 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
10620 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
10630 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
10640 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
10650 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
10660 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
10670 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
10680 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
10690 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
106a0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
106b0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
106c0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
106d0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
106e0 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
106f0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10700 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
10710 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
10720 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
10730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10740 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
10750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
10760 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
10770 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
10780 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
10790 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
107a0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
107b0 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
107c0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
107d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
107e0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
107f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
10800 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
10810 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
10820 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
10830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10840 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
10850 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
10860 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
10870 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10880 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10890 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
108a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
108b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
108c0 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
108d0 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
108e0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
108f0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
10900 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
10910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10920 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
10930 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
10940 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
10950 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
10960 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
10970 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
10980 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
10990 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
109a0 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
109b0 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
109c0 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
109d0 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
109e0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
109f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
10a00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
10a10 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
10a20 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10a30 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
10a40 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
10a50 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
10a60 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10a70 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
10a80 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
10a90 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
10aa0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
10ab0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10ac0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10ad0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10ae0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10af0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10b00 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
10b10 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
10b20 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10b30 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
10b40 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
10b50 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
10b60 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10b70 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
10b80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10b90 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
10ba0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
10bb0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
10bc0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
10bd0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10be0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10bf0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10c00 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
10c10 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
10c20 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
10c30 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
10c40 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
10c50 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
10c60 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10c70 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
10c80 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
10c90 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
10ca0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
10cb0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
10cc0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
10cd0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
10ce0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10cf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10d00 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
10d10 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
10d20 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
10d30 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
10d40 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
10d50 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
10d60 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
10d70 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
10d80 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
10d90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
10da0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
10db0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10dc0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
10dd0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
10de0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10df0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10e00 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
10e10 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10e20 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10e30 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
10e40 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
10e50 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
10e60 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
10e70 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
10e80 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
10e90 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
10ea0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
10eb0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
10ec0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
10ed0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
10ee0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10ef0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10f00 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10f10 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10f20 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10f30 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10f40 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10f50 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
10f60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10f70 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
10f80 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
10f90 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
10fa0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
10fb0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10fc0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10fd0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10fe0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10ff0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
11000 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
11010 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
11020 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
11030 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
11040 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
11050 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11060 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11070 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11080 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11090 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
110a0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
110b0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
110c0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
110d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
110e0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
110f0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
11100 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
11110 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
11120 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
11130 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
11140 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
11150 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11160 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11170 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11180 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11190 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
111a0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
111b0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
111c0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
111d0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
111e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
111f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
11200 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
11210 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
11220 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
11230 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11240 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11250 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11260 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11270 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11280 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11290 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
112a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
112b0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
112c0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
112d0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
112e0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
112f0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
11300 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
11310 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
11320 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
11330 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11340 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11350 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11360 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11370 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11380 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11390 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
113a0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
113b0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
113c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
113d0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
113e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
113f0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11400 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11410 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
11420 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
11430 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11440 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11450 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11460 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11470 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11480 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11490 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
114a0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
114b0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
114c0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
114d0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
114e0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
114f0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11500 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11510 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11520 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11530 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11540 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11550 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11560 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11570 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11580 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11590 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
115a0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
115b0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
115c0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
115d0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
115e0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
115f0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11600 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11610 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11620 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11630 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11640 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11650 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11660 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11670 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11680 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11690 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
116a0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
116b0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
116c0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
116d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
116e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
116f0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11700 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11710 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11720 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11730 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11740 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11750 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
11760 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
11770 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11780 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
11790 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
117a0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
117b0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
117c0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
117d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
117e0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
117f0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11800 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
11810 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
11820 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
11830 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
11840 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
11850 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
11860 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
11870 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
11880 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
11890 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
118a0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
118b0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
118c0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
118d0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
118e0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
118f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11900 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
11910 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11920 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
11930 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
11940 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
11950 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
11960 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
11970 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
11980 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
11990 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
119a0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
119b0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
119c0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
119d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
119e0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
119f0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11a00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11a10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11a20 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11a30 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11a40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11a50 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
11a60 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
11a70 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
11a80 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
11a90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11aa0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
11ab0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11ac0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11ad0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11ae0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11af0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b00 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
11b10 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
11b20 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
11b30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11b40 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11b50 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
11b60 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
11b70 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
11b80 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
11b90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11ba0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
11bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11bc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11bd0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
11be0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11bf0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11c00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11c10 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11c20 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11c30 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11c40 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11c50 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11c60 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
11c70 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11c80 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
11c90 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
11ca0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
11cb0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
11cc0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
11cd0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
11ce0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11cf0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11d00 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11d10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11d20 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11d30 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11d40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11d50 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11d60 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
11d70 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
11d80 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
11d90 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
11da0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
11db0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
11dc0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11dd0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
11de0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11df0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11e10 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
11e20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11e30 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11e40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11e50 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
11e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11e70 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
11e80 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11e90 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11ea0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11eb0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11ec0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11ed0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
11ee0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11ef0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11f00 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11f10 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11f20 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11f30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11f40 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11f50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
11f60 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
11f70 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
11f80 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
11f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
11fa0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11fb0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11fc0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11fd0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11fe0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11ff0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
12000 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
12010 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
12020 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
12030 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
12040 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
12050 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12060 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12070 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12080 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12090 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
120a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
120b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
120c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
120d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
120e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
120f0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12100 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
12110 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
12120 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
12130 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12140 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12150 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12160 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12170 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12180 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12190 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
121a0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
121b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
121c0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
121d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
121e0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
121f0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12200 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12210 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12220 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12230 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12240 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12250 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12260 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12270 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12280 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12290 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
122a0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
122b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
122c0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
122d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
122e0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
122f0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
12300 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
12310 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12320 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
12330 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12340 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12350 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12360 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12370 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12390 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
123a0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
123b0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
123c0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
123d0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
123e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
123f0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
12400 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
12410 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
12420 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
12430 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12440 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12450 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12460 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12470 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12480 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12490 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
124a0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
124b0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
124c0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
124d0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
124e0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
124f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12500 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12510 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12520 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12540 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12550 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12560 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12570 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12580 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12590 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
125a0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
125b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
125c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
125d0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
125e0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
125f0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12600 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12610 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
12620 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12630 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12640 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12650 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12660 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12670 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12680 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12690 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
126a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
126b0 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
126c0 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
126d0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
126e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
126f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12700 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12710 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12720 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12730 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12740 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12750 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12760 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12770 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12780 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12790 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
127a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
127b0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
127c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
127d0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
127e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
127f0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12800 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
12810 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
12820 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
12830 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
12840 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
12850 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12860 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
12870 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12880 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12890 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
128a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
128b0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
128c0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
128d0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
128e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
128f0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12900 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
12910 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
12920 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12940 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
12950 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12960 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
12970 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
12980 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12990 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
129a0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
129b0 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
129c0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
129d0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
129e0 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
129f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
12a00 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
12a10 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
12a20 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12a30 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
12a40 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
12a50 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12a60 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12a70 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12a80 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12a90 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12aa0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12ab0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12ac0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12ad0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12ae0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12af0 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12b10 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
12b20 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
12b30 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12b40 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12b50 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
12b60 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12b70 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12b80 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
12b90 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
12ba0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
12bb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12bc0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12bd0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12be0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12c00 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
12c10 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12c20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
12c30 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
12c40 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
12c50 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
12c60 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
12c70 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
12c80 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
12c90 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12ca0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
12cb0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12cc0 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12cd0 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12ce0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12cf0 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12d00 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12d10 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12d30 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12d40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12d50 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12d60 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
12d70 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
12d80 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
12d90 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
12da0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12db0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12dc0 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12dd0 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12de0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12df0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12e00 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12e10 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
12e20 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
12e30 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
12e40 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
12e50 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
12e60 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
12e70 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
12e80 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
12e90 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
12ea0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
12eb0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12ec0 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12ed0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12ee0 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
12ef0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12f00 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12f10 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12f20 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12f30 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12f40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12f50 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
12f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12f70 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
12f80 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
12f90 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
12fa0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12fb0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12fc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12fd0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
12fe0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12ff0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
13000 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
13010 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
13020 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
13030 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
13040 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
13050 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
13060 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13070 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
13080 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
13090 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
130a0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
130b0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
130c0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
130d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
130e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
130f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13100 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
13110 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13120 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
13130 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
13140 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
13150 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
13160 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13170 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
13180 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
13190 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
131a0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
131b0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
131c0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
131d0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
131e0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
131f0 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
13200 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
13210 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
13220 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
13230 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
13240 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
13250 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
13260 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
13270 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
13280 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
13290 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
132a0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
132b0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
132c0 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
132d0 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
132e0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
132f0 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
13300 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
13310 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
13320 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13330 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
13340 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
13350 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13360 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13370 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
13380 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
13390 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
133a0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
133b0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
133c0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
133d0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
133e0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
133f0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
13400 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
13410 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
13420 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
13430 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
13440 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
13450 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
13460 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
13470 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13480 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
13490 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
134a0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
134b0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
134c0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
134d0 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
134e0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
134f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
13500 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
13510 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
13520 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
13530 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13540 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13550 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
13560 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
13570 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
13580 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
13590 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
135a0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
135b0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
135c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
135d0 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
135e0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
135f0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
13600 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
13610 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
13620 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
13630 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
13640 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
13650 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
13660 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
13670 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13680 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
13690 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
136a0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
136b0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
136c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
136d0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
136e0 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
136f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
13700 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
13710 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
13720 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
13730 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
13740 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
13750 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
13760 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
13770 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
13780 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
13790 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
137a0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
137b0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
137c0 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
137d0 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
137e0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
137f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13800 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13810 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13820 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13830 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13840 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13850 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13860 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
13870 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
13880 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
13890 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
138a0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
138b0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
138c0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
138d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
138e0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
138f0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13900 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13910 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13920 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13930 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13940 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13960 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13970 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
13980 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13990 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
139a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
139b0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
139c0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
139d0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
139e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
139f0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13a00 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13a10 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13a20 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13a30 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13a40 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13a50 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
13a60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13a70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13a80 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13a90 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
13aa0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13ab0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13ac0 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13ad0 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13ae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13af0 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13b00 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13b10 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13b20 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13b30 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13b40 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13b50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13b60 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13b70 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13b80 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13b90 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13ba0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13bb0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13bc0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13bd0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13be0 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13bf0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13c00 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13c10 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13c30 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
13c40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13c50 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
13c60 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13c70 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13c80 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13c90 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13ca0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13cb0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13cc0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13cd0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13ce0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13cf0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
13d00 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13d10 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13d20 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13d30 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
13d40 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13d50 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13d60 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13d70 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
13d80 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
13d90 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
13da0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
13db0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
13dc0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
13dd0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
13de0 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
13df0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13e00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13e10 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13e20 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13e30 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13e40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13e50 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
13e60 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
13e70 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
13e80 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
13e90 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
13ea0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13eb0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13ec0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13ed0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
13ee0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13ef0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13f00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13f10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13f30 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
13f40 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13f50 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
13f60 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13f70 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
13f80 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
13f90 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
13fa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13fb0 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
13fc0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13fd0 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
13fe0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13ff0 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
14000 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
14010 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
14020 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
14030 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
14040 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
14050 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
14060 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
14070 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14080 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
14090 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
140a0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
140b0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
140c0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
140d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
140e0 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
140f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14100 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
14110 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14120 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14130 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14140 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14150 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14170 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14180 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14190 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
141a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
141b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
141c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
141d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
141e0 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
141f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14200 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14210 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
14220 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
14230 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14240 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14250 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
14260 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
14270 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
14280 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
14290 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
142a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
142b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
142c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
142d0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
142e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
142f0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14300 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
14310 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14320 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14330 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
14350 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14360 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
14370 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
14380 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
14390 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
143a0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
143b0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
143c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
143d0 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
143e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
143f0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14410 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
14420 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
14430 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
14440 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
14450 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
14460 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14470 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14480 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
14490 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
144a0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
144b0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
144c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
144d0 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
144e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
144f0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
14500 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
14510 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
14520 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
14530 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
14540 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
14550 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
14560 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
14570 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
14580 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
14590 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
145a0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
145b0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
145c0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
145d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
145e0 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
145f0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
14600 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
14610 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14620 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
14630 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
14640 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
14650 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
14660 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
14670 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
14680 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
14690 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
146a0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
146b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
146c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
146d0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
146e0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
146f0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
14700 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
14710 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
14720 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
14730 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
14740 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14750 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
14760 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
14770 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
14780 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
14790 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
147a0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
147b0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
147c0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
147d0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
147e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
147f0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
14800 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
14810 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
14820 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
14830 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
14840 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
14850 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
14860 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
14870 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14880 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
14890 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
148a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
148b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
148c0 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
148d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
148e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
148f0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14900 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
14910 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
14920 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14930 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
14940 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
14950 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
14960 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
14970 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
14980 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
14990 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
149a0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
149b0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
149c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
149d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
149e0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
149f0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14a00 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14a10 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14a20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14a30 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14a40 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14a50 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14a60 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14a70 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14a80 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14a90 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14aa0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14ab0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14ac0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14ad0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14ae0 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14af0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14b00 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14b10 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14b20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14b30 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14b40 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14b50 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14b60 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14b70 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14b80 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14b90 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14ba0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14bb0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14bc0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14bd0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14be0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14bf0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14c00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14c10 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14c20 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14c30 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14c40 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
14c50 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
14c60 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
14c70 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
14c80 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
14c90 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
14ca0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14cb0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
14cc0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14cd0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14ce0 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20  ptimizer.  ^The 
14cf0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14d00 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
14d10 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
14d20 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
14d30 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
14d40 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
14d50 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
14d60 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
14d70 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
14d80 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
14d90 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
14da0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14db0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14dc0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14dd0 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14de0 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14df0 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14e00 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
14e10 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
14e20 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
14e30 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
14e40 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14e50 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
14e60 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
14e70 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
14e80 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
14e90 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
14ea0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
14eb0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14ec0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14ed0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14ee0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14ef0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14f00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f10 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f30 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14f40 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14f50 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
14f60 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
14f70 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
14f80 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
14f90 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
14fa0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
14fb0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14fc0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14fd0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14fe0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15000 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15010 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15020 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15030 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15040 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15050 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15060 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15070 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
15080 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15090 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
150a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
150b0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
150c0 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
150d0 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
150e0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
150f0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15100 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15110 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15120 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15130 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15140 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15150 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15160 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
15170 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
15180 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
15190 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
151a0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
151b0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
151c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
151d0 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
151e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
151f0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15210 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15220 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15230 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15240 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15250 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15260 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
15270 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
15280 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15290 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
152a0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
152b0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
152c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
152d0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
152e0 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
152f0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15300 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15310 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15320 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15330 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15340 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15350 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15360 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
15370 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
15380 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15390 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
153a0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
153b0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
153c0 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
153d0 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
153e0 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
153f0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15400 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15410 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15420 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15440 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15450 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15460 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
15470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15480 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15490 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
154a0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
154b0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
154c0 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
154d0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
154e0 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
154f0 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15500 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15510 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15520 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15530 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15540 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15550 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15560 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
15570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
15580 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15590 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
155a0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
155b0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
155c0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
155d0 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
155e0 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
155f0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15600 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
15610 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
15620 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
15630 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
15640 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
15650 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
15660 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
15670 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
15680 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
15690 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
156a0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
156b0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
156c0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
156d0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
156e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
156f0 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15700 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15710 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15720 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
15730 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15740 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15750 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15760 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15770 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
15780 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
15790 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
157a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
157b0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a  ed for Windows.*
157c0 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
157d0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
157e0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
157f0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  acro defined..**
15800 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
15810 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
15820 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
15830 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
15840 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
15850 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
15860 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
15870 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c  eated heap..** <
15880 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
15890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
158a0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
158b0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
158c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
158d0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
158e0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
158f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15900 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
15910 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15920 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15930 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
15940 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15950 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15960 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15970 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
15980 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
15990 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
159a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
159b0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
159c0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
159d0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
159e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
159f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15a00 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
15a10 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15a20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15a30 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
15a40 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
15a50 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
15a60 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
15a70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a80 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
15a90 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
15aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15ab0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15ac0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15ad0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15ae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15af0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15b00 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
15b10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15b20 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
15b30 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
15b40 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
15b50 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
15b60 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
15b70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b80 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
15b90 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
15ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15bb0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
15bc0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
15bd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15be0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15bf0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15c00 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15c10 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
15c20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
15c30 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
15c40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15c50 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
15c60 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
15c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c80 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
15c90 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
15ca0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15cb0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15cc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15cd0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15ce0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15cf0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15d00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15d10 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15d20 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
15d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15d40 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15d50 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
15d60 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
15d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15d80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
15d90 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
15da0 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
15db0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
15dc0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15dd0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15de0 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15df0 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  Byte */../*.** C
15e00 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
15e10 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
15e20 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
15e30 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
15e40 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
15e50 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
15e60 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
15e70 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
15e80 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
15e90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15ea0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
15eb0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15ec0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
15ed0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
15ee0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
15ef0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15f00 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
15f10 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
15f20 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
15f30 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
15f40 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
15f50 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
15f60 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
15f70 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
15f80 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
15f90 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
15fa0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
15fb0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
15fc0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
15fd0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15fe0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15ff0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
16000 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
16010 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
16020 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
16030 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16040 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
16050 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
16060 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
16070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
16080 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16090 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
160a0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
160b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
160c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
160d0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
160e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
160f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
16100 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
16110 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
16120 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16130 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
16140 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
16150 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16160 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
16170 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
16180 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
16190 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
161a0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
161b0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
161c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
161d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
161e0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
161f0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
16200 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
16210 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
16220 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
16230 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
16240 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
16250 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16260 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
16270 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
16280 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
16290 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
162a0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
162b0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
162c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
162d0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
162e0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
162f0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
16300 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
16310 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
16320 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
16330 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
16340 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
16350 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
16360 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
16370 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
16380 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
16390 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
163a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
163b0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
163c0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
163d0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
163e0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
163f0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
16400 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
16410 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16420 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
16430 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
16440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
16450 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
16460 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
16470 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
16480 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
16490 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
164a0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
164b0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
164c0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
164d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
164e0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
164f0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
16500 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
16510 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
16520 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
16530 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
16540 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
16550 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
16560 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
16570 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
16580 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
16590 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
165a0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
165b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
165c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
165d0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
165e0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
165f0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16600 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
16610 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16620 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
16630 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
16640 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
16650 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
16660 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16670 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16680 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16690 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
166a0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
166b0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
166c0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
166d0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
166e0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
166f0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16700 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16710 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
16720 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16730 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16740 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16750 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
16760 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16770 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16780 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
16790 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
167a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
167b0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
167c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
167d0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
167e0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
167f0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
16800 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
16810 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16820 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16830 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16840 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
16850 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
16860 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16870 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
16880 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
16890 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
168a0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
168b0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
168c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
168d0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
168e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
168f0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16900 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16910 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
16920 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16930 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
16940 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
16950 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
16960 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
16970 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16980 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16990 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
169a0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
169b0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
169c0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
169d0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
169e0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
169f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
16a00 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
16a10 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
16a20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
16a30 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
16a40 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
16a50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16a60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16a70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
16a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16a90 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16aa0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
16ab0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
16ac0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16ad0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16ae0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
16af0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
16b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16b10 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16b20 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
16b30 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
16b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16b50 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
16b60 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
16b70 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
16b80 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
16b90 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16ba0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
16bb0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16bc0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
16bd0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
16be0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
16bf0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
16c00 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
16c10 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
16c20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
16c30 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
16c40 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lity..*/.SQLITE_
16c50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
16c60 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
16c70 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
16c80 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
16c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
16ca0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
16cb0 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
16cc0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
16cd0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
16ce0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
16cf0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
16d00 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
16d10 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
16d20 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
16d30 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
16d40 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
16d50 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
16d60 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
16d70 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
16d80 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
16d90 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
16da0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
16db0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
16dc0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
16dd0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
16de0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
16df0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
16e00 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
16e10 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
16e20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
16e30 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
16e40 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
16e50 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
16e60 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
16e70 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
16e80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
16e90 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
16ea0 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
16eb0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
16ec0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
16ed0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
16ee0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16ef0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
16f00 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
16f10 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
16f20 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
16f30 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
16f40 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
16f50 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
16f60 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
16f70 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
16f80 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
16f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
16fa0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
16fb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
16fc0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
16fd0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
16fe0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
16ff0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
17000 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
17010 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
17020 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
17030 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
17040 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
17050 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
17060 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
17070 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
17080 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
17090 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
170a0 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
170b0 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
170c0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
170d0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
170e0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
170f0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
17100 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
17110 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
17120 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
17130 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
17140 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
17150 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
17160 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
17170 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
17180 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
17190 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
171a0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
171b0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
171c0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
171d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
171e0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
171f0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
17200 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
17210 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
17220 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
17230 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
17240 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
17250 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
17260 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
17270 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
17280 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
17290 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
172a0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
172b0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
172c0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
172d0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
172e0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
172f0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
17300 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
17310 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
17320 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
17330 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
17340 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
17350 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
17360 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
17370 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
17380 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
17390 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
173a0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
173b0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
173c0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
173d0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
173e0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
173f0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
17400 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
17410 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
17420 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
17430 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
17440 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
17450 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
17460 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17470 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17480 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17490 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
174a0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
174b0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
174c0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
174d0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
174e0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
174f0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
17500 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
17510 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
17520 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
17530 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
17540 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
17550 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
17560 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17570 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
17580 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
17590 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
175a0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
175b0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
175c0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
175d0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
175e0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
175f0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
17600 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17610 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17620 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
17630 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
17640 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
17650 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17660 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17670 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
17680 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
17690 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
176a0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
176b0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
176c0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
176d0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
176e0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
176f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
17700 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
17710 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
17720 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
17730 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
17740 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
17750 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
17760 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
17770 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
17780 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
17790 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
177a0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
177b0 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
177c0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
177d0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
177e0 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
177f0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17800 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
17810 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
17820 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
17830 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
17840 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
17850 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
17860 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17870 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
17880 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
17890 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
178a0 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
178b0 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
178c0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
178d0 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
178e0 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
178f0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
17900 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
17910 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
17920 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
17930 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
17940 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
17950 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
17960 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
17970 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
17980 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
17990 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
179a0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
179b0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
179c0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
179d0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
179e0 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
179f0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
17a00 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
17a10 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
17a20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
17a30 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
17a40 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
17a50 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
17a60 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
17a70 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
17a80 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
17a90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17aa0 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
17ab0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
17ac0 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
17ad0 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
17ae0 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
17af0 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
17b00 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
17b10 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
17b20 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
17b30 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
17b40 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
17b50 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
17b60 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
17b70 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
17b80 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
17b90 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
17ba0 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
17bb0 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
17bc0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
17bd0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
17be0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
17bf0 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
17c00 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
17c10 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
17c20 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
17c30 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17c40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17c50 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
17c60 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
17c70 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
17c80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17c90 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
17ca0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
17cb0 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
17cc0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
17cd0 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
17ce0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
17cf0 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
17d00 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
17d10 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
17d20 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
17d30 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
17d40 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
17d50 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
17d60 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
17d70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
17d80 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
17d90 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
17da0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17db0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
17dc0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
17dd0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
17de0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
17df0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17e00 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
17e10 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17e20 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
17e30 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
17e40 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
17e50 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
17e60 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
17e70 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
17e80 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
17e90 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
17ea0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
17eb0 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
17ec0 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
17ed0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
17ee0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
17ef0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
17f00 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
17f10 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
17f20 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
17f30 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
17f40 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
17f50 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17f60 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
17f70 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
17f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17f90 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
17fa0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
17fb0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
17fc0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
17fd0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
17fe0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
17ff0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
18000 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
18010 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
18020 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
18030 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
18040 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
18050 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
18060 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
18070 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
18080 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
18090 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
180a0 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
180b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
180c0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
180d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
180e0 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
180f0 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
18100 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18110 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18120 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
18130 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
18140 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
18150 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
18160 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
18170 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
18180 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
18190 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
181a0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
181b0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
181c0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
181d0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
181e0 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
181f0 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
18200 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
18210 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
18220 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
18230 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
18240 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
18250 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
18260 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
18270 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
18280 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
18290 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
182a0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
182b0 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
182c0 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
182d0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
182e0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
182f0 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
18300 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
18310 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
18320 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
18330 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
18340 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
18350 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
18360 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
18370 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
18380 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
18390 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
183a0 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
183b0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
183c0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
183d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
183e0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
183f0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
18400 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
18410 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18420 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18430 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
18440 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18450 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18460 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18470 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
18480 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
18490 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
184a0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
184b0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
184c0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
184d0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
184e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
184f0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18500 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18510 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
18520 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
18530 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
18540 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
18550 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
18560 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
18570 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
18580 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
18590 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
185a0 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
185b0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
185c0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
185d0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
185e0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
185f0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
18600 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
18610 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
18620 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
18630 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
18640 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
18650 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
18660 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
18670 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
18680 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
18690 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
186a0 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
186b0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
186c0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
186d0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
186e0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
186f0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18700 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
18710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18720 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
18730 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
18740 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
18750 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
18760 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
18770 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
18780 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
18790 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
187a0 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
187b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
187c0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
187d0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
187e0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
187f0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
18800 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
18810 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
18820 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
18830 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
18840 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
18850 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
18860 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
18870 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
18880 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
18890 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
188a0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
188b0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
188c0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
188d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
188e0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
188f0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
18900 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
18910 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
18920 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
18930 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
18940 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
18950 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
18960 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
18970 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
18980 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
18990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
189a0 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
189b0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
189c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
189d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
189e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
189f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
18a00 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
18a10 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
18a20 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
18a30 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
18a40 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
18a50 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
18a60 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
18a70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18a80 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
18a90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
18aa0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
18ab0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
18ac0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
18ad0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
18ae0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
18af0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
18b00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
18b10 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
18b20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18b30 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
18b40 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
18b50 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
18b60 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
18b70 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
18b80 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
18b90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18ba0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18bb0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
18bc0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
18bd0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
18be0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
18bf0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
18c00 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
18c10 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
18c20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
18c30 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
18c40 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
18c50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
18c60 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
18c70 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
18c80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18c90 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
18ca0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
18cb0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
18cc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
18cd0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
18ce0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
18cf0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
18d00 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
18d10 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
18d20 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
18d30 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18d40 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
18d50 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
18d60 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
18d70 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
18d80 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
18d90 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
18da0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
18db0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
18dc0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
18dd0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
18de0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18df0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
18e00 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
18e10 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
18e20 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
18e30 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
18e40 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
18e50 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
18e60 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
18e70 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
18e80 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
18e90 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
18ea0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
18eb0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
18ec0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
18ed0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
18ee0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
18ef0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
18f00 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
18f10 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
18f20 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
18f30 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
18f40 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
18f50 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
18f60 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
18f70 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
18f80 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
18f90 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
18fa0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
18fb0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
18fc0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
18fd0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
18fe0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
18ff0 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
19000 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
19010 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
19020 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
19030 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
19040 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
19050 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
19060 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19070 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
19080 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
19090 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
190a0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
190b0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
190c0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
190d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
190e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
190f0 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
19100 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
19110 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
19120 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
19130 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
19140 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
19150 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
19160 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
19170 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
19180 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
19190 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
191a0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
191b0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
191c0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
191d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
191e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
191f0 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
19200 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
19210 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
19220 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
19230 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
19240 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
19250 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
19260 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
19270 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
19280 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
19290 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
192a0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
192b0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
192c0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54   order..*/.SQLIT
192d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
192e0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
192f0 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c   char *sql);.SQL
19300 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
19310 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
19320 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
19330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19340 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
19350 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
19360 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
19370 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
19380 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
19390 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
193a0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
193b0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
193c0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
193d0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
193e0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
193f0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
19400 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
19410 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
19420 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
19430 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
19440 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
19450 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
19460 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
19470 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
19480 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
19490 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
194a0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
194b0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
194c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
194d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
194e0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
194f0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
19500 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
19510 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19520 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19530 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19540 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
19550 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
19560 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
19570 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
19580 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
19590 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
195a0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
195b0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
195c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
195d0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
195e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
195f0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19600 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
19610 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
19620 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
19630 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
19640 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
19650 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
19660 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
19670 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19680 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
19690 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
196a0 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
196b0 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
196c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
196d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
196e0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
196f0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
19700 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
19710 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
19720 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
19730 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
19740 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
19750 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
19760 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
19770 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
19780 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
19790 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
197a0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
197b0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
197c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
197d0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
197e0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
197f0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19800 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19810 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
19820 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
19830 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
19840 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
19850 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
19860 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
19870 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
19880 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
19890 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
198a0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
198b0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
198c0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
198d0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
198e0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
198f0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19900 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
19910 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
19920 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
19930 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
19940 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
19950 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
19960 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
19970 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
19980 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
19990 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
199a0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
199b0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
199c0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
199d0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
199e0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
199f0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
19a00 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
19a10 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
19a20 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
19a30 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
19a40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
19a50 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
19a60 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
19a70 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
19a80 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
19a90 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
19aa0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
19ab0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
19ac0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
19ad0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
19ae0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
19af0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
19b00 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
19b10 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
19b20 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
19b30 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
19b40 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
19b50 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
19b60 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
19b70 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
19b80 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
19b90 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
19ba0 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
19bb0 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
19bc0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
19bd0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
19be0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
19bf0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
19c00 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
19c10 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
19c20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
19c30 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
19c40 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
19c50 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
19c60 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
19c70 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
19c80 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
19c90 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
19ca0 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
19cb0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
19cc0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
19cd0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
19ce0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
19cf0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
19d00 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
19d10 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
19d20 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
19d30 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
19d40 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
19d50 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
19d60 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
19d70 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
19d80 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
19d90 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
19da0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
19db0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
19dc0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
19dd0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
19de0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
19df0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
19e00 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
19e10 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
19e20 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
19e30 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
19e40 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
19e50 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
19e60 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
19e70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19e80 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19e90 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19ea0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
19eb0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
19ec0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
19ed0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
19ee0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
19ef0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
19f00 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
19f10 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
19f20 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
19f30 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
19f40 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
19f50 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
19f60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
19f70 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
19f80 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
19f90 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
19fa0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
19fb0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19fc0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
19fd0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
19fe0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
19ff0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1a000 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1a010 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1a020 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1a030 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1a040 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a050 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1a060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1a070 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1a080 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1a0a0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1a0b0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1a0c0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1a0d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1a0e0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1a0f0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1a100 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1a110 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
1a120 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
1a130 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
1a140 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
1a150 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
1a160 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
1a170 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
1a180 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
1a190 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
1a1a0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
1a1b0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
1a1c0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1a1d0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
1a1e0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
1a1f0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
1a200 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1a210 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1a220 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
1a230 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
1a240 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
1a250 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
1a260 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
1a270 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
1a280 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
1a290 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1a2a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1a2b0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1a2c0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1a2d0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1a2e0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1a2f0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1a300 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1a310 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1a320 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1a330 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1a340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a350 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
1a360 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
1a370 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1a380 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
1a390 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
1a3a0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
1a3b0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
1a3c0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
1a3d0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
1a3e0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
1a3f0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c  leared.)^.*/.SQL
1a400 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1a410 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a420 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1a430 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1a440 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1a450 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1a460 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1a470 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1a480 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1a490 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1a4a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1a4b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a4c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1a4d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1a4e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1a4f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1a500 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1a510 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a520 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a530 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a540 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a550 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1a560 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1a570 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1a580 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1a590 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1a5a0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1a5b0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1a5c0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1a5d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1a5e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1a5f0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1a600 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1a610 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a620 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1a630 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1a640 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1a650 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1a660 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a670 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1a680 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a690 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1a6a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a6b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1a6c0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1a6d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1a6e0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1a6f0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1a700 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1a710 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1a720 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1a730 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1a740 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a750 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1a760 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1a770 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1a780 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1a790 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1a7a0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1a7b0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1a7c0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1a7d0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1a7e0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1a7f0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1a800 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a810 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1a820 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1a830 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1a840 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1a850 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1a860 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1a870 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1a880 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1a890 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1a8a0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1a8b0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1a8c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1a8d0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1a8e0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1a8f0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1a900 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1a910 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1a920 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1a930 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1a940 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1a950 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1a960 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1a970 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a980 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a990 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1a9a0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1a9b0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1a9c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1a9d0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1a9e0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1a9f0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1aa00 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1aa10 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1aa20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1aa30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1aa40 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1aa50 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1aa60 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1aa70 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1aa80 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1aa90 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1aaa0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1aab0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1aac0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1aad0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1aae0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1aaf0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1ab00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ab10 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1ab20 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1ab30 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1ab40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ab50 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1ab60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ab70 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1ab80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ab90 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1aba0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1abb0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1abc0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1abd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1abe0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1abf0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1ac00 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1ac10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ac20 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1ac30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ac40 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1ac50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ac60 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1ac70 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1ac80 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ac90 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1aca0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1acb0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1acc0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1acd0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1ace0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1acf0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1ad00 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1ad10 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1ad20 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1ad30 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1ad40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1ad50 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1ad60 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1ad70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ad80 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1ad90 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1ada0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1adb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1adc0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1add0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1ade0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1adf0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1ae00 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1ae10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1ae20 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1ae30 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1ae40 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1ae50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1ae60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1ae70 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1ae80 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1ae90 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1aea0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1aeb0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1aec0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1aed0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1aee0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1aef0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1af00 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1af10 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1af20 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1af30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1af40 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1af50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1af60 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1af70 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1af80 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1af90 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1afa0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1afb0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1afc0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1afd0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1afe0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1aff0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1b000 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1b010 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1b020 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1b030 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1b040 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1b050 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1b060 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1b070 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1b080 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1b090 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b0a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1b0b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  I int sqlite3_ge
1b0c0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1b0d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1b0e0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1b0f0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1b100 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1b110 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1b120 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1b130 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1b140 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1b150 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1b160 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1b170 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1b180 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1b190 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1b1a0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1b1b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1b1c0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1b1d0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1b1e0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1b1f0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1b200 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1b210 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ere */.);.SQLITE
1b220 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1b230 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1b240 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1b250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1b260 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1b270 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1b280 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1b290 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1b2a0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1b2b0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1b2c0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1b2d0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1b2e0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
1b2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b300 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1b310 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1b320 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1b330 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1b340 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1b350 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1b360 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1b370 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1b380 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1b390 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1b3a0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1b3b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1b3c0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1b3d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1b3e0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1b3f0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1b400 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1b410 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1b420 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1b430 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1b440 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1b450 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1b460 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1b470 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1b480 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1b490 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1b4a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1b4b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1b4c0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1b4d0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1b4e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1b4f0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1b500 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1b510 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1b520 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1b530 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1b540 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1b550 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1b560 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1b570 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1b580 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1b590 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1b5a0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1b5b0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1b5c0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1b5d0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1b5e0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1b5f0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b600 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1b610 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1b620 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1b630 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1b640 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1b650 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1b660 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1b670 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1b680 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1b690 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1b6a0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1b6b0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1b6c0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1b6d0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1b6e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1b6f0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1b700 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1b710 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1b720 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1b730 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1b740 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1b750 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1b760 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1b770 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1b780 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1b790 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1b7a0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1b7b0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1b7c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1b7d0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1b7e0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1b7f0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1b800 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1b810 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1b820 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1b830 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1b840 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1b850 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1b860 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1b870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b880 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1b890 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1b8a0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1b8b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b8c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1b8d0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1b8e0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1b8f0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1b900 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1b910 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1b920 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1b930 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1b940 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1b950 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1b960 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1b970 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1b980 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1b990 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
1b9a0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1b9b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1b9c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1b9d0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1b9e0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1b9f0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1ba00 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1ba10 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1ba20 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1ba30 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1ba40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1ba50 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1ba60 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1ba70 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1ba80 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1ba90 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1baa0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1bab0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1bac0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1bad0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1bae0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1baf0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1bb00 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1bb10 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1bb20 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1bb30 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1bb40 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bb50 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1bb60 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1bb70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1bb80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1bb90 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1bba0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1bbb0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bbc0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1bbd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1bbe0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1bbf0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1bc00 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1bc10 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1bc20 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1bc30 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bc40 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bc50 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bc60 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bc70 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bc80 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1bc90 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1bca0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1bcb0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1bcc0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1bcd0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1bce0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1bcf0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1bd00 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bd10 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1bd20 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1bd30 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1bd40 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1bd50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1bd60 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1bd70 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1bd80 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1bd90 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1bda0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1bdb0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1bdc0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1bdd0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1bde0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1bdf0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1be00 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1be10 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1be20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1be30 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1be40 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1be50 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1be60 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1be70 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1be80 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1be90 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1bea0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1beb0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1bec0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1bed0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1bee0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1bef0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1bf00 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1bf10 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1bf20 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1bf30 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1bf40 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1bf50 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1bf60 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1bf70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bf80 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1bf90 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1bfa0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1bfb0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1bfc0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1bfd0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1bfe0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1bff0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c000 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1c010 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1c020 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1c030 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1c040 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1c050 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1c060 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1c070 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1c080 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c090 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1c0a0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1c0b0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1c0c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1c0d0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1c0e0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1c0f0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1c100 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1c110 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1c120 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1c130 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c140 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1c150 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1c160 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1c170 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1c180 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1c190 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1c1a0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1c1b0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1c1c0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1c1d0 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
1c1e0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1c1f0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1c200 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49  char*,...);.SQLI
1c210 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1c220 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1c230 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1c240 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  st);.SQLITE_API 
1c250 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1c260 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1c270 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1c280 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1c290 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1c2a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1c2b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1c2c0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1c2d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1c2e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1c2f0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1c300 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1c310 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1c320 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1c330 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1c340 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1c350 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1c360 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1c370 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1c380 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1c390 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1c3a0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1c3b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1c3c0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1c3d0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1c3e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1c3f0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1c400 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1c410 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1c420 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1c430 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1c440 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1c450 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1c460 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1c470 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1c480 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1c490 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1c4a0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1c4b0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1c4c0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1c4d0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1c4e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1c4f0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1c500 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1c510 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1c520 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1c530 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1c540 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1c550 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c560 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1c570 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1c580 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1c590 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1c5a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1c5b0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1c5c0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1c5d0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1c5e0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1c5f0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1c600 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1c610 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1c620 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1c630 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1c640 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1c650 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1c660 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1c670 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1c680 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1c690 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1c6a0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1c6b0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1c6c0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1c6d0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1c6e0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1c6f0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1c700 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1c710 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1c720 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1c730 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1c740 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1c750 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1c760 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1c770 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1c780 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1c790 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1c7a0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1c7b0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1c7c0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1c7d0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1c7e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1c7f0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1c800 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
1c810 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
1c820 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1c830 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1c840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c850 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1c860 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
1c870 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
1c880 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
1c890 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1c8a0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
1c8b0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
1c8c0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
1c8d0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
1c8e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c8f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1c900 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c910 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1c920 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1c930 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1c940 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c950 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1c960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c970 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1c980 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
1c990 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c9a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c9b0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1c9c0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1c9d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1c9e0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1c9f0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1ca00 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ca10 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
1ca20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ca30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1ca40 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
1ca50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1ca60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1ca70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1ca80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1ca90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1caa0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1cab0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
1cac0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
1cad0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1cae0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1caf0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1cb00 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1cb10 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1cb20 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1cb30 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1cb40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1cb50 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1cb60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1cb70 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
1cb80 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1cb90 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1cba0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1cbb0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
1cbc0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
1cbd0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
1cbe0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1cbf0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cc00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1cc10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
1cc20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1cc30 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1cc40 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1cc50 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1cc60 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1cc70 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1cc80 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1cc90 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1cca0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1ccb0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1ccc0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1ccd0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1cce0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1ccf0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1cd00 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1cd10 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1cd20 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1cd30 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1cd40 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1cd50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1cd60 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1cd70 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1cd80 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1cd90 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1cda0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1cdb0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1cdc0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1cdd0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1cde0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1cdf0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1ce00 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1ce10 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1ce20 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1ce30 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1ce40 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1ce50 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1ce60 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1ce70 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1ce80 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1ce90 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1cea0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1ceb0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1cec0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1ced0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1cee0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1cef0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1cf00 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1cf10 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1cf20 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1cf30 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1cf40 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1cf50 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1cf60 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1cf70 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1cf80 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1cf90 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1cfa0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1cfb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1cfc0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1cfd0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1cfe0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1cff0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1d000 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1d010 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1d020 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1d030 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1d040 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1d050 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1d060 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1d070 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1d080 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1d090 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1d0a0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1d0b0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1d0c0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1d0d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1d0e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1d0f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1d100 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1d110 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1d120 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
1d130 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
1d140 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1d150 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1d160 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1d170 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1d180 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1d190 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1d1a0 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1d1b0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1d1c0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1d1d0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1d1e0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1d1f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1d200 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1d210 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1d220 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1d230 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1d240 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1d250 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1d260 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1d270 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1d280 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1d290 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1d2a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1d2b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1d2c0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1d2d0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1d2e0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1d2f0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1d300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1d310 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1d320 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1d330 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1d340 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1d350 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d360 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1d370 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1d380 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1d390 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1d3a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1d3b0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1d3c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1d3d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d3e0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1d3f0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1d400 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1d410 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d420 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1d430 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1d440 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1d450 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1d460 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1d470 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1d480 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1d490 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1d4a0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1d4b0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1d4c0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1d4d0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1d4e0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1d4f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d500 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1d510 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1d520 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1d530 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d540 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1d550 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1d560 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1d570 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d580 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1d590 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1d5a0 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1d5b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1d5c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1d5d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1d5e0 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
1d5f0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1d600 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1d610 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1d620 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1d630 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1d640 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1d650 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1d660 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1d670 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1d680 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1d690 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1d6a0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1d6b0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1d6c0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1d6d0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1d6e0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1d6f0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1d700 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1d710 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1d720 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1d730 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1d740 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1d750 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1d760 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1d770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1d780 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1d790 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1d7a0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1d7b0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1d7c0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1d7d0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1d7e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1d7f0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1d800 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1d810 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1d820 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
1d830 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 61  n one, then P ca
1d840 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1d850 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1d860 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1d870 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1d880 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1d890 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1d8a0 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1d8b0 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20   than one, then 
1d8c0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1d8d0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1d8e0 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ess.** obtained 
1d8f0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1d900 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1d910 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1d920 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1d930 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1d940 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1d950 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1d960 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1d970 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75  then.** the pseu
1d980 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1d990 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1d9a0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1d9b0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1d9c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1d9d0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1d9e0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
1d9f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1da00 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1da10 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1da20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1da30 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1da40 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1da50 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1da60 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1da70 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1da80 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1da90 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1daa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dab0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1dac0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1dad0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1dae0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1daf0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1db00 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1db10 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1db20 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1db30 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1db40 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1db50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1db60 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1db70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1db80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1db90 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1dba0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1dbb0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1dbc0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1dbd0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1dbe0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1dbf0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1dc00 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1dc10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1dc20 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1dc30 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1dc40 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1dc50 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1dc60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dc70 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1dc80 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1dc90 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1dca0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1dcb0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1dcc0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1dcd0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1dce0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1dcf0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1dd00 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1dd10 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1dd20 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1dd30 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1dd40 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1dd50 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1dd60 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1dd70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dd80 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1dd90 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1dda0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1ddb0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1ddc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1ddd0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1dde0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ddf0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1de00 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1de10 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1de20 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1de30 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1de40 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1de50 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1de60 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1de70 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1de80 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1de90 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1dea0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1deb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1dec0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1ded0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1dee0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1def0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1df00 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1df10 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1df20 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1df30 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1df40 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1df50 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1df60 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1df70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1df80 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1df90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1dfa0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1dfb0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1dfc0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1dfd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1dfe0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1dff0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e000 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1e010 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1e020 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1e030 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1e040 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1e050 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1e060 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1e070 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1e080 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1e090 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1e0a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1e0b0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1e0c0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1e0d0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1e0e0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1e0f0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1e100 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1e110 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1e120 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1e130 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1e140 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1e150 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1e160 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1e170 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1e180 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1e190 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1e1a0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1e1b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1e1c0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1e1d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1e1e0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1e1f0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1e200 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1e210 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1e220 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1e230 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1e240 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1e250 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1e260 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1e270 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1e280 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1e290 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1e2a0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1e2b0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1e2c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e2d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1e2e0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1e2f0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1e300 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1e310 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1e320 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1e330 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1e340 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1e350 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1e360 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1e370 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1e380 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e390 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1e3a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1e3b0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1e3c0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1e3d0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1e3e0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1e3f0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1e400 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1e410 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1e420 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1e430 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1e440 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1e450 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1e460 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1e470 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1e480 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1e490 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1e4a0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1e4b0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1e4c0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1e4d0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1e4e0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1e4f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e500 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1e510 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1e520 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1e530 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1e540 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1e550 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1e560 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1e570 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1e580 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1e590 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1e5a0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1e5b0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1e5c0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1e5d0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1e5e0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1e5f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1e600 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1e610 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1e620 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1e630 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1e640 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1e650 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1e660 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1e670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1e680 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1e690 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1e6a0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1e6b0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1e6c0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1e6d0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1e6e0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1e6f0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1e700 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1e710 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1e720 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1e730 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1e740 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1e750 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1e760 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1e770 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1e780 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1e790 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1e7a0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1e7b0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1e7c0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1e7d0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1e7e0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1e7f0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1e800 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1e810 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1e820 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1e830 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1e840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1e850 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1e860 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e870 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1e880 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1e890 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1e8a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1e8b0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1e8c0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1e8d0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1e8e0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1e8f0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1e900 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1e910 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1e920 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1e930 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1e940 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1e950 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1e960 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1e970 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1e980 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1e990 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1e9a0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1e9b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1e9c0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1e9d0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1e9e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e9f0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1ea00 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1ea10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1ea20 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1ea30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ea40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ea50 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1ea60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1ea70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1ea80 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1ea90 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1eaa0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1eab0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1eac0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1ead0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1eae0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1eaf0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1eb00 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1eb10 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1eb20 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1eb30 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1eb40 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1eb50 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1eb60 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
1eb70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1eb80 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1eb90 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1eba0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1ebb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1ebc0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ebd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1ebe0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1ebf0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1ec00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ec10 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1ec20 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1ec30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1ec40 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1ec50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ec60 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1ec70 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1ec80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1ec90 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1eca0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1ecb0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1ecc0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1ecd0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1ece0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1ecf0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1ed00 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ed10 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1ed20 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1ed30 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1ed40 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1ed50 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1ed60 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1ed70 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1ed80 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1ed90 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1eda0 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1edb0 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1edc0 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1edd0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1ede0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1edf0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1ee00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1ee10 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1ee20 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1ee30 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1ee40 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1ee50 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1ee60 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1ee70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1ee80 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1ee90 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1eea0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1eeb0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1eec0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1eed0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1eee0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1eef0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1ef00 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1ef10 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1ef20 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1ef30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ef40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1ef50 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1ef60 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1ef70 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1ef80 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1ef90 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1efa0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1efb0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1efc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1efd0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1efe0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1eff0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1f000 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1f010 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1f020 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1f030 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1f040 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1f050 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1f060 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1f070 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1f080 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1f090 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1f0a0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1f0b0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1f0c0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1f0d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1f0e0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1f0f0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1f100 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f110 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1f120 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1f130 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1f140 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1f150 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1f160 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1f170 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f180 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1f190 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1f1a0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1f1b0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1f1c0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1f1d0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1f1e0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1f1f0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1f200 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1f210 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1f220 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1f230 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
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 20 33  ************** 3
1f260 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1f270 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1f280 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f290 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1f2a0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1f2b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1f2c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f2d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f2e0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1f2f0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1f300 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f310 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f330 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1f340 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1f350 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1f360 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f380 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1f390 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1f3a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f3b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f3c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f3d0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1f3e0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1f3f0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1f400 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f410 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f420 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1f430 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1f440 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f450 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f460 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f470 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1f480 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1f490 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1f4a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f4b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f4c0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1f4d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1f4e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f4f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f500 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1f510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1f520 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f530 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f540 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f550 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1f560 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1f570 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f580 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f590 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f5a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1f5b0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1f5c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f5d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f5e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f5f0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1f600 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1f610 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f620 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f630 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f640 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1f650 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1f660 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f670 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f680 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f690 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1f6a0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1f6b0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1f6c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f6d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f6e0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1f6f0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1f700 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1f710 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f730 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1f740 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1f750 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f760 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f780 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1f790 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1f7a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f7b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f7c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1f7d0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1f7e0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1f7f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f800 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1f820 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1f830 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1f840 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1f850 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1f860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1f870 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1f880 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1f890 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1f8a0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f8b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1f8c0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1f8d0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1f8e0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f8f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f900 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1f910 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1f920 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1f930 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1f940 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f950 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1f960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f970 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1f980 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f990 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f9a0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1f9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1f9c0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1f9d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f9e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f9f0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1fa00 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1fa10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1fa20 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1fa30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fa40 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1fa50 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1fa60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1fa70 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1fa80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fa90 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1faa0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1fab0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1fac0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fad0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fae0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1faf0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1fb00 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1fb10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fb20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fb30 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1fb40 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1fb50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fb60 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1fb70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fb80 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1fb90 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1fba0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fbb0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1fbc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fbd0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1fbe0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1fbf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1fc00 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1fc10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fc20 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1fc30 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1fc40 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1fc50 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1fc60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fc70 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1fc80 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1fc90 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
1fca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1fcb0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
1fcc0 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
1fcd0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1fce0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
1fcf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1fd00 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1fd10 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1fd20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1fd30 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1fd40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1fd50 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1fd60 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1fd70 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1fd80 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1fd90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1fda0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1fdb0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1fdc0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1fdd0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1fde0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1fdf0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1fe00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1fe10 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1fe20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1fe30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fe40 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1fe50 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1fe60 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1fe70 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1fe80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1fe90 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1fea0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1feb0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1fec0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1fed0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1fee0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1fef0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1ff00 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1ff10 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1ff20 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1ff30 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1ff40 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1ff50 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1ff60 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1ff70 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
1ff80 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
1ff90 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
1ffa0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
1ffb0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
1ffc0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
1ffd0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
1ffe0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
1fff0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
20000 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
20020 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20030 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20040 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20050 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20060 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20070 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20080 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20090 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
200a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
200b0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
200c0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
200d0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
200e0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
200f0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
20100 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
20110 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20120 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
20130 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20140 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20150 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20160 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20170 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20180 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20190 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
201a0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
201b0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
201c0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
201d0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
201e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
201f0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
20200 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
20210 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
20220 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
20230 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20240 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20250 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20260 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20270 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20280 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20290 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
202a0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
202b0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
202c0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
202d0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
202e0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
202f0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
20300 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
20310 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
20320 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
20330 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
20340 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
20350 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
20360 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
20370 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
20380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
20390 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
203a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
203b0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
203c0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
203d0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
203e0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
203f0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
20400 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
20410 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
20420 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
20430 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
20440 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
20450 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
20460 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
20470 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
20480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20490 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
204a0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
204b0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
204c0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
204d0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
204e0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
204f0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
20500 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
20510 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
20520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
20530 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
20540 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
20550 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
20560 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
20570 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
20580 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
20590 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
205a0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
205b0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
205c0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
205d0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
205e0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
205f0 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
20600 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
20610 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
20620 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
20630 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
20640 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
20650 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
20660 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
20670 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20680 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
20690 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
206a0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
206b0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
206c0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
206d0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
206e0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
206f0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
20700 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20710 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
20720 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
20730 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
20740 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
20750 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
20760 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
20770 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
20780 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
20790 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
207a0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
207b0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
207c0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
207d0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
207e0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
207f0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
20800 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20810 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
20820 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
20830 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
20840 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
20850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
20860 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
20870 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
20880 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
20890 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
208a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
208b0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
208c0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
208d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
208e0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
208f0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
20900 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
20910 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
20920 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
20930 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
20940 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
20950 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
20960 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
20970 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
20980 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
20990 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
209a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
209b0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
209c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
209d0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
209e0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
209f0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
20a00 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
20a10 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20a20 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
20a30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
20a40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20a50 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
20a60 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
20a70 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
20a80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20a90 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
20aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
20ab0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
20ac0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
20ad0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
20ae0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
20af0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
20b00 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
20b10 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
20b20 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
20b30 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
20b40 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
20b50 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
20b60 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
20b70 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
20b80 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
20b90 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
20ba0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
20bb0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20bc0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
20bd0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
20be0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
20bf0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
20c00 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
20c10 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
20c20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
20c30 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
20c40 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
20c50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
20c60 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
20c70 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
20c80 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
20c90 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
20ca0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
20cb0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
20cc0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
20cd0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
20ce0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
20cf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
20d00 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
20d10 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
20d20 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
20d30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20d40 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
20d50 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
20d60 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
20d70 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
20d80 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
20d90 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
20da0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
20db0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
20dc0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
20dd0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
20de0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
20df0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
20e00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20e10 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
20e20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
20e30 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
20e40 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20e50 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
20e60 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
20e70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20e80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
20e90 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
20ea0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
20eb0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
20ec0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
20ed0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
20ee0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
20ef0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
20f00 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
20f10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
20f20 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
20f30 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
20f40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20f50 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
20f60 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
20f70 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
20f80 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
20f90 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
20fa0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
20fb0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
20fc0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
20fd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20fe0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
20ff0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21000 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
21010 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
21020 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
21030 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
21040 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
21050 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
21060 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21070 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
21080 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
21090 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
210a0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
210b0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
210c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
210d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
210e0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
210f0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
21100 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
21110 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21120 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
21130 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
21140 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
21150 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
21160 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
21170 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
21180 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
21190 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
211a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
211b0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
211c0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
211d0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
211e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
211f0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21200 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
21210 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21220 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21230 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21240 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21250 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
21260 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
21270 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
21280 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
21290 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
212a0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
212b0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
212c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
212d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
212e0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
212f0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
21300 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
21310 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21320 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
21330 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
21340 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
21350 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
21360 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
21370 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21380 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
21390 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
213a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
213b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
213c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
213d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
213e0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
213f0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
21400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21410 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
21420 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
21430 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
21440 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
21450 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
21460 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
21470 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
21480 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21490 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
214a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
214b0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
214c0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
214d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
214e0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
214f0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
21500 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
21510 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
21520 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
21530 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
21540 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21550 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
21560 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
21570 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
21580 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
21590 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
215a0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
215b0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
215c0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
215d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
215e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
215f0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
21600 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
21610 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
21620 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
21630 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
21640 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21650 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
21660 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21670 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
21680 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
21690 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
216a0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
216b0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
216c0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
216d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
216e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
216f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
21700 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
21710 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
21720 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
21730 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21740 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
21750 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
21760 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
21770 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
21780 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
21790 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
217a0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
217b0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
217c0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
217d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
217e0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
217f0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
21800 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
21810 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
21820 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
21830 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
21840 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
21850 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
21860 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
21870 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
21880 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
21890 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
218a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
218b0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
218c0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
218d0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
218e0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
218f0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
21900 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
21910 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
21920 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
21930 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
21940 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
21950 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
21960 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
21970 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
21980 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
21990 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
219a0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
219b0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
219c0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
219d0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
219e0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
219f0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
21a00 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
21a10 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
21a20 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
21a30 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
21a40 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
21a50 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
21a60 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
21a70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
21a80 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
21a90 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
21aa0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
21ab0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
21ac0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
21ad0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
21ae0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
21af0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
21b00 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
21b10 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
21b20 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
21b30 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
21b40 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
21b50 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
21b60 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
21b70 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
21b80 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
21b90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21ba0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
21bb0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
21bc0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21bd0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
21be0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
21bf0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
21c00 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
21c10 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
21c20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
21c30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
21c40 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
21c50 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
21c60 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
21c70 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
21c80 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
21c90 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
21ca0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
21cb0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
21cc0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
21cd0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
21ce0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
21cf0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
21d00 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
21d10 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
21d20 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
21d30 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
21d40 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
21d50 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
21d60 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
21d70 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
21d80 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
21d90 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
21da0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
21db0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
21dc0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
21dd0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
21de0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
21df0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
21e00 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
21e10 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
21e20 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
21e30 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
21e40 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
21e50 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
21e60 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
21e70 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
21e80 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
21e90 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
21ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
21eb0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
21ec0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
21ed0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
21ee0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
21ef0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
21f00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
21f10 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
21f20 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
21f30 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
21f40 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
21f50 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
21f60 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
21f70 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
21f80 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
21f90 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
21fa0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
21fb0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
21fc0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
21fd0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
21fe0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
21ff0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
22000 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
22010 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
22020 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
22030 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
22040 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
22050 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
22060 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
22070 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
22080 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
22090 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
220a0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
220b0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
220c0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
220d0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
220e0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
220f0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
22100 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
22110 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
22120 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
22130 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
22140 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
22150 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
22160 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
22170 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
22180 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
22190 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
221a0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
221b0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
221c0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
221d0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
221e0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
221f0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
22200 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
22210 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
22220 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
22230 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
22240 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
22250 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
22260 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
22270 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
22280 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
22290 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
222a0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
222b0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
222c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
222d0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
222e0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
222f0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
22300 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
22310 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
22320 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
22330 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
22340 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
22350 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22360 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22370 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22380 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
22390 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
223a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
223b0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
223c0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
223d0 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
223e0 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
223f0 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
22400 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
22410 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
22420 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22430 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22440 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22450 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22460 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
22470 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
22480 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
22490 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
224a0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
224b0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
224c0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
224d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
224e0 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
224f0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
22500 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
22510 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
22520 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22530 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
22540 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
22550 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
22560 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
22570 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
22580 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
22590 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
225a0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
225b0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
225c0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
225d0 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
225e0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
225f0 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
22600 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
22610 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
22620 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
22630 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
22640 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
22650 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
22660 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
22670 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
22680 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
22690 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
226a0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
226b0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
226c0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
226d0 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
226e0 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
226f0 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
22700 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
22710 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
22720 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
22730 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22740 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22750 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
22760 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
22770 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22780 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22790 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
227a0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
227b0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
227c0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
227d0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
227e0 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
227f0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22800 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
22810 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
22820 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
22830 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22840 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
22850 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
22860 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
22870 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
22880 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
22890 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
228a0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
228b0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
228c0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
228d0 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
228e0 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
228f0 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
22900 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
22910 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
22920 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
22930 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
22940 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
22950 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22960 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
22970 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22980 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
22990 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
229a0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
229b0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
229c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
229d0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
229e0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
229f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22a00 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
22a10 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
22a20 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
22a30 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
22a40 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
22a50 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
22a60 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
22a70 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
22a80 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
22a90 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
22aa0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
22ab0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
22ac0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
22ad0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
22ae0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
22af0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
22b00 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
22b10 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
22b20 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
22b30 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
22b40 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
22b50 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
22b60 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
22b70 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
22b80 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
22b90 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
22ba0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
22bb0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
22bc0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
22bd0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
22be0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
22bf0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
22c00 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
22c10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
22c20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
22c30 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
22c40 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
22c50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
22c60 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
22c70 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
22c80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
22c90 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
22ca0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
22cb0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
22cc0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
22cd0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
22ce0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
22cf0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
22d00 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
22d10 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
22d20 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
22d30 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
22d40 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
22d50 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
22d60 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
22d70 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
22d80 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
22d90 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
22da0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
22db0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
22dc0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
22dd0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
22de0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
22df0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
22e00 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
22e10 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
22e20 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
22e30 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
22e40 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
22e50 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
22e60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
22e70 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
22e80 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
22e90 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
22ea0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
22eb0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
22ec0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
22ed0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
22ee0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
22ef0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
22f00 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
22f10 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
22f20 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
22f30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22f40 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
22f50 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
22f60 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
22f70 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22f80 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
22f90 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
22fa0 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
22fb0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
22fc0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
22fd0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
22fe0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
22ff0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
23000 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
23010 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
23020 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
23030 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
23040 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
23050 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
23060 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
23070 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
23080 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
23090 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
230a0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
230b0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
230c0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
230d0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
230e0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
230f0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
23100 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
23110 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
23120 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
23130 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
23140 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23150 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
23160 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
23170 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
23180 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
23190 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
231a0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
231b0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
231c0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
231d0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
231e0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
231f0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
23200 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
23210 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
23220 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
23230 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
23240 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
23250 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
23260 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
23270 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
23280 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
23290 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
232a0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
232b0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
232c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
232d0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
232e0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
232f0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
23300 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
23310 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
23320 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
23330 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
23340 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
23350 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
23360 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
23370 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
23380 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
23390 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
233a0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
233b0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
233c0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
233d0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
233e0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
233f0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
23400 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
23410 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
23420 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
23430 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
23440 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
23450 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
23460 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
23470 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
23480 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
23490 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
234a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
234b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
234c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
234d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
234e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
234f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23500 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23510 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23520 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23530 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
23540 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
23550 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
23560 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
23570 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23580 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
23590 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
235a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
235b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
235c0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
235d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
235e0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
235f0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
23600 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
23610 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
23620 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
23630 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
23640 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23650 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
23660 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
23670 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
23680 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
23690 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
236a0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
236b0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
236c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
236d0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
236e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
236f0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
23700 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
23710 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
23720 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
23730 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
23740 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
23750 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
23760 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
23770 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
23780 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
23790 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
237a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
237b0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
237c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
237d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
237e0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
237f0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
23800 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
23810 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
23820 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
23830 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
23840 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
23850 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
23860 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
23870 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
23880 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
23890 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
238a0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
238b0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
238c0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
238d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
238e0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
238f0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
23900 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
23910 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
23920 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
23930 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
23940 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
23950 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23960 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
23970 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
23980 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
23990 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
239a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
239b0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
239c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
239d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
239e0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
239f0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
23a00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23a10 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
23a20 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
23a30 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
23a40 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
23a50 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
23a60 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
23a70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
23a80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
23a90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23aa0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
23ab0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
23ac0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
23ad0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
23ae0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
23af0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
23b00 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
23b10 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
23b20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
23b30 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
23b40 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
23b50 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23b60 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
23b70 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
23b80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
23b90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23ba0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
23bb0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
23bc0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
23bd0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
23be0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
23bf0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
23c00 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
23c10 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
23c20 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
23c30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
23c40 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
23c50 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
23c60 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
23c70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23c80 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
23c90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
23ca0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
23cb0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
23cc0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
23cd0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
23ce0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
23cf0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
23d00 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
23d10 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
23d20 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
23d30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
23d40 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
23d50 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
23d60 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
23d70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
23d80 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
23d90 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
23da0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
23db0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23dc0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
23dd0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23de0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
23df0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
23e00 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
23e10 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
23e20 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
23e30 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
23e40 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
23e50 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
23e60 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
23e70 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
23e80 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
23e90 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
23ea0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
23eb0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
23ec0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
23ed0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23ee0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
23ef0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
23f00 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
23f10 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54   *zParam);.SQLIT
23f20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
23f30 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
23f40 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
23f50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
23f60 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
23f70 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  t);.SQLITE_API s
23f80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
23f90 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
23fa0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
23fb0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
23fc0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
23fd0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
23fe0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
23ff0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
24000 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
24010 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24020 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
24030 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
24040 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
24050 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
24060 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
24070 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
24080 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
24090 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
240a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
240b0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
240c0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
240d0 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
240e0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
240f0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
24100 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
24110 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
24120 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
24130 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
24140 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
24150 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
24160 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
24170 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
24180 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
24190 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
241a0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
241b0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
241c0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
241d0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
241e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
241f0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
24200 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
24210 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
24220 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
24230 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
24240 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
24250 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
24260 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
24270 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
24280 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
24290 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
242a0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
242b0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
242c0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
242d0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
242e0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
242f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
24300 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
24310 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
24320 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
24330 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
24340 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
24350 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
24360 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
24370 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
24380 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
24390 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
243a0 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
243b0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
243c0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
243d0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
243e0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
243f0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
24400 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
24410 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
24420 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
24430 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
24440 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
24450 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
24460 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
24470 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
24480 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
24490 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
244a0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
244b0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
244c0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
244d0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
244e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
244f0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
24500 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
24510 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
24520 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
24530 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
24540 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
24550 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
24560 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
24570 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
24580 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
24590 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
245a0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
245b0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
245c0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
245d0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
245e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
245f0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
24600 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
24610 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
24620 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
24630 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
24640 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
24650 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
24660 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
24670 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
24680 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
24690 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
246a0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
246b0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
246c0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
246d0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
246e0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
246f0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
24700 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
24710 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
24720 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
24730 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
24740 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
24750 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
24760 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
24770 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
24780 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54  be set..*/.SQLIT
24790 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
247a0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
247b0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
247c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
247d0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
247e0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
247f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
24800 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
24810 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  msg(sqlite3*);.S
24820 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
24830 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
24840 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
24850 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
24860 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24870 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
24880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24890 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
248a0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
248b0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
248c0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
248d0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
248e0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
248f0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
24900 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
24910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
24920 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
24930 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
24940 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
24950 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
24960 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
24970 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
24980 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
24990 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
249a0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
249b0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
249c0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
249d0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
249e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
249f0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
24a00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
24a10 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
24a20 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
24a30 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
24a40 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
24a50 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
24a60 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
24a70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
24a80 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
24a90 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
24aa0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
24ab0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24ac0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
24ad0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
24ae0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
24af0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
24b00 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
24b10 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
24b20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
24b30 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
24b40 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
24b50 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
24b60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
24b70 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
24b80 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
24b90 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
24ba0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
24bb0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
24bc0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
24bd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
24be0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
24bf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
24c00 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
24c10 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
24c20 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
24c30 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
24c40 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
24c50 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
24c60 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
24c70 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
24c80 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
24c90 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
24ca0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24cb0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
24cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24cd0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
24ce0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
24cf0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
24d00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
24d10 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
24d20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
24d30 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
24d40 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
24d50 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
24d60 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
24d70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
24d80 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
24d90 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
24da0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
24db0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
24dc0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
24dd0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
24de0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
24df0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
24e00 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
24e10 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
24e20 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
24e30 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
24e40 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
24e50 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
24e60 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
24e70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
24e80 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
24e90 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
24ea0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
24eb0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
24ec0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
24ed0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
24ee0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
24ef0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
24f00 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
24f10 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
24f20 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
24f30 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
24f40 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
24f50 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
24f60 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
24f70 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
24f80 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
24f90 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
24fa0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
24fb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24fc0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
24fd0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
24fe0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
24ff0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
25000 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
25010 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
25020 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25030 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
25040 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
25050 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
25060 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
25070 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
25080 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
25090 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
250a0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
250b0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
250c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
250d0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
250e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
250f0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
25100 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
25110 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
25120 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25130 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
25140 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25150 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25160 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25170 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25180 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25190 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
251a0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
251b0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
251c0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
251d0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
251e0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
251f0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
25200 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
25210 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
25220 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25230 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
25240 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25250 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25260 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25270 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25280 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25290 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
252a0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
252b0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
252c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
252d0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
252e0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
252f0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
25300 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
25310 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
25320 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25330 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
25340 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25350 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25360 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25370 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25380 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25390 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
253a0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
253b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
253c0 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
253d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
253e0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
253f0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
25400 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
25410 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
25420 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
25430 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
25440 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
25450 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
25460 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
25470 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
25480 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
25490 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
254a0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
254b0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
254c0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
254d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
254e0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
254f0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
25500 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
25510 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
25520 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
25530 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
25540 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
25550 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
25560 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
25570 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
25580 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
25590 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
255a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
255b0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
255c0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
255d0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
255e0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
255f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25600 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
25610 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
25620 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
25630 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
25640 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
25650 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
25660 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
25670 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
25690 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
256a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
256b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
256c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
256d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
256e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
256f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
25700 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
25710 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
25720 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
25730 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
25740 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
25750 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
25760 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
25770 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25780 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
25790 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
257a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
257b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
257c0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
257d0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
257e0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
257f0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
25800 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25810 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
25820 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
25830 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25840 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
25850 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25860 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
25870 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
25880 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
25890 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
258a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
258b0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
258c0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
258d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
258e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
258f0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
25900 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
25910 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
25920 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
25930 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
25940 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
25950 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
25960 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
25970 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
25980 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
25990 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
259a0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
259b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
259c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
259d0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
259e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
259f0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
25a00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25a10 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
25a20 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
25a30 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
25a40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
25a50 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
25a60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
25a70 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
25a80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25a90 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
25aa0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
25ab0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
25ac0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25ad0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25ae0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
25af0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
25b00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
25b10 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
25b20 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
25b30 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
25b40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
25b50 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
25b60 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
25b70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25b80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25b90 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
25ba0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25bb0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25bc0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
25bd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
25be0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
25bf0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
25c00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
25c10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25c20 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25c30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
25c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25c50 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
25c60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25c70 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
25c80 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
25c90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
25ca0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
25cb0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
25cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25cd0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
25ce0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
25cf0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
25d00 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
25d10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
25d20 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
25d30 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
25d40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25d50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
25d60 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
25d70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
25d80 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
25d90 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
25da0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
25db0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
25dc0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
25dd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25de0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
25df0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
25e00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25e10 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
25e20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
25e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25e40 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
25e50 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
25e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25e70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
25e80 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
25e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25ea0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25eb0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
25ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25ed0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
25ee0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
25ef0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
25f00 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
25f10 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
25f20 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
25f30 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
25f40 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
25f50 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
25f60 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
25f70 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
25f80 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
25f90 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
25fa0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
25fb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
25fc0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
25fd0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
25fe0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
25ff0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
26000 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
26010 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
26020 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
26030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26040 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
26050 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
26060 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
26070 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
26080 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
26090 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
260a0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
260b0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
260c0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
260d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
260e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
260f0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
26100 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
26110 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
26120 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
26130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26140 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
26150 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
26160 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
26170 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
26180 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
26190 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
261a0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
261b0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
261c0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
261d0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
261e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
261f0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
26200 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
26210 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
26220 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
26230 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
26240 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
26250 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
26260 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
26270 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
26280 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
26290 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
262a0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
262b0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
262c0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
262d0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
262e0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
262f0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
26300 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
26310 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
26320 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
26330 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
26340 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
26350 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
26360 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
26370 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
26380 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
26390 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
263a0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
263b0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
263c0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
263d0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
263e0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
263f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
26400 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
26410 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
26420 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
26430 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
26440 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
26450 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
26460 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
26470 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
26480 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
26490 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
264a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
264b0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
264c0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
264d0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
264e0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
264f0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
26500 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
26510 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
26520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26530 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
26540 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
26550 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
26560 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
26570 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
26580 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
26590 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
265a0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
265b0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
265c0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
265d0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
265e0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
265f0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
26600 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
26610 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
26620 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
26630 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
26640 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
26650 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
26660 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26670 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
26680 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
26690 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
266a0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
266b0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
266c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
266d0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
266e0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
266f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
26700 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
26710 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
26720 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
26730 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26740 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
26750 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26760 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
26770 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
26780 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
26790 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
267a0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
267b0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
267c0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
267d0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
267e0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
267f0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
26800 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
26810 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
26820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
26830 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
26840 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
26850 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
26860 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
26870 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
26880 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
26890 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
268a0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
268b0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
268c0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
268d0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
268e0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
268f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
26900 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
26910 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
26920 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
26930 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
26940 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
26950 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
26960 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
26970 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
26980 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
26990 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
269a0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
269b0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
269c0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
269d0 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
269e0 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
269f0 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
26a00 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
26a10 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
26a20 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
26a30 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
26a40 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
26a50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26a60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
26a70 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
26a80 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
26a90 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
26aa0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
26ab0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
26ac0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
26ad0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26ae0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
26af0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
26b00 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
26b10 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
26b20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
26b30 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
26b40 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
26b50 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
26b60 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
26b70 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
26b80 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
26b90 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
26ba0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
26bb0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
26bc0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
26bd0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
26be0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
26bf0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
26c00 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
26c10 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
26c20 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
26c30 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
26c40 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
26c50 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
26c60 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
26c70 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
26c80 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
26c90 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
26ca0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
26cb0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
26cc0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
26cd0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
26ce0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
26cf0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
26d00 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
26d10 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
26d20 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
26d30 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
26d40 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
26d50 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
26d60 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
26d70 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
26d80 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
26d90 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
26da0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
26db0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
26dc0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
26dd0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
26de0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
26df0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
26e00 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
26e10 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
26e20 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
26e30 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
26e40 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
26e50 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
26e60 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
26e70 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
26e80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
26e90 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
26ea0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
26eb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
26ec0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
26ed0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
26ee0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26ef0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26f00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26f10 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26f20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
26f30 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
26f40 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
26f50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
26f60 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
26f70 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
26f80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26f90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
26fa0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26fb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26fc0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
26fd0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26fe0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26ff0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27000 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27020 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
27030 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27040 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27050 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27060 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27080 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
27090 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
270a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
270b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
270c0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
270d0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
270e0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
270f0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
27100 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27110 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
27120 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
27130 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
27140 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
27150 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27160 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27170 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
27180 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27190 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
271a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
271b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
271c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
271d0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
271e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
271f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27200 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27210 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27220 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27230 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27240 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27250 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27260 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
27270 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27280 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27290 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
272a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
272b0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
272c0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
272d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
272e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
272f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27300 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
27310 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
27320 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
27330 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27340 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27350 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27360 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27370 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27380 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27390 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
273a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
273b0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
273c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
273d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
273e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
273f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
27400 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
27410 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
27420 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
27430 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
27440 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
27450 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
27460 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
27470 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
27480 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
27490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
274a0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
274b0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
274c0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
274d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
274e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
274f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
27500 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
27510 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27520 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
27530 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27550 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
27560 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
27570 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
27580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27590 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
275a0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
275b0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
275c0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
275d0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
275e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
275f0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
27600 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
27610 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27620 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27630 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
27640 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
27650 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27660 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
27670 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
27680 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
27690 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
276a0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
276b0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
276c0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
276d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
276e0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
276f0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
27700 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
27710 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
27720 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
27730 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
27740 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
27750 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
27760 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
27770 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
27780 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
27790 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
277a0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
277b0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
277c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
277d0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
277e0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
277f0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
27800 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27810 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
27820 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
27830 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
27840 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
27850 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
27860 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
27870 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
27880 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
27890 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
278a0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
278b0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
278c0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
278d0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
278e0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
278f0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
27900 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
27910 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
27920 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
27930 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
27940 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
27950 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
27960 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
27970 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
27980 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
27990 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
279a0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
279b0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
279c0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
279d0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
279e0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
279f0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
27a00 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
27a10 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
27a20 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
27a30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
27a40 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
27a50 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
27a60 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27a70 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27a80 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51  s on disk..*/.SQ
27a90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27aa0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27ab0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
27ac0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27ad0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
27ae0 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
27af0 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
27b00 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a  Been Reset.**.**
27b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
27b20 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
27b30 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
27b40 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
27b50 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
27b60 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
27b70 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
27b80 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
27b90 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
27ba0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
27bb0 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70   not run to comp
27bc0 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61  letion and/or ha
27bd0 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72  s not .** been r
27be0 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
27bf0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
27c00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27c10 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
27c20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
27c30 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
27c40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
27c50 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
27c60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
27c70 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
27c80 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
27c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27ca0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
27cb0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
27cc0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
27cd0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
27ce0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
27cf0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
27d00 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
27d10 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
27d20 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
27d30 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
27d40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
27d50 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27d60 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
27d70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
27d80 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
27d90 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
27da0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
27db0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
27dc0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
27dd0 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
27de0 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
27df0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
27e00 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
27e10 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
27e20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
27e30 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
27e40 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
27e50 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27e60 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
27e70 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
27e80 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
27e90 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
27ea0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
27eb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27ec0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
27ed0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
27ee0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27ef0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
27f00 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
27f10 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
27f20 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
27f30 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
27f40 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
27f50 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
27f60 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
27f70 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
27f80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27f90 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
27fa0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
27fb0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
27fc0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
27fd0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
27fe0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
27ff0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
28000 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
28010 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
28020 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
28030 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
28040 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
28050 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
28060 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
28070 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
28080 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
28090 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
280a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
280b0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
280c0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
280d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
280e0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
280f0 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
28100 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
28110 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
28120 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
28130 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
28140 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
28150 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
28160 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
28170 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
28180 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
28190 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
281a0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
281b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
281c0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
281d0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
281e0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
281f0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28200 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
28210 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
28220 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
28230 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
28240 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
28250 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
28260 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
28270 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
28280 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
28290 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
282a0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
282b0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
282c0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
282d0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
282e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
282f0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
28300 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
28310 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
28320 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
28330 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
28340 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28350 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
28360 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
28370 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
28380 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
28390 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
283a0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
283b0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
283c0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
283d0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
283e0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
283f0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
28400 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28410 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
28420 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
28430 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
28440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28450 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28460 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
28470 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
28480 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
28490 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
284a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
284b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
284c0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
284d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
284e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
284f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
28500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
28510 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
28520 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
28530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28540 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
28550 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
28560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
28570 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
28580 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
28590 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
285a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
285b0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
285c0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
285d0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
285e0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
285f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28600 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
28610 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
28620 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
28630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28640 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
28650 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
28660 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
28670 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
28680 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
28690 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
286a0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
286b0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
286c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
286d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
286e0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
286f0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
28700 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
28710 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
28720 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
28730 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28740 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28750 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
28760 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
28770 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
28780 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
28790 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
287a0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
287b0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
287c0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
287d0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
287e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
287f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28800 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
28810 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
28820 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
28830 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
28840 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
28850 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
28860 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
28870 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
28880 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
28890 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
288a0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
288b0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
288c0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
288d0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
288e0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
288f0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
28900 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
28910 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
28920 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
28930 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
28940 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
28950 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28960 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
28970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28980 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
28990 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
289a0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
289b0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
289c0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
289d0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
289e0 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
289f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
28a00 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
28a10 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
28a20 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
28a30 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
28a40 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
28a50 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
28a60 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
28a70 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
28a80 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
28a90 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
28aa0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
28ab0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
28ac0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
28ad0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
28ae0 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
28af0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
28b00 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
28b10 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
28b20 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
28b30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
28b40 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
28b50 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
28b60 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
28b70 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
28b80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28b90 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
28ba0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
28bb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
28bc0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
28bd0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
28be0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28bf0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
28c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
28c10 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
28c20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
28c30 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
28c40 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
28c50 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
28c60 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28c70 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
28c80 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
28c90 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
28ca0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
28cb0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
28cc0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
28cd0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
28ce0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
28cf0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
28d00 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
28d10 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
28d20 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
28d30 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
28d40 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
28d50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28d60 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
28d70 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
28d80 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
28d90 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
28da0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
28db0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
28dc0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
28dd0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
28de0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
28df0 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
28e00 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
28e10 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
28e20 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
28e30 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
28e40 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
28e50 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
28e60 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
28e70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
28e80 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
28e90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28ea0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
28eb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28ec0 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
28ed0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
28ee0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
28ef0 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
28f00 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
28f10 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
28f20 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
28f30 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
28f40 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
28f50 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
28f60 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
28f70 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
28f80 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
28f90 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28fa0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28fb0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
28fc0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
28fd0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
28fe0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
28ff0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
29000 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
29010 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
29020 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
29030 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
29040 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29050 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29060 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
29070 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
29080 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
29090 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
290a0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
290b0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
290c0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
290d0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
290e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
290f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
29100 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
29110 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
29120 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
29130 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
29140 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
29150 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29160 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
29170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29180 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
29190 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
291a0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
291b0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
291c0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
291d0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
291e0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
291f0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
29200 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
29210 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
29220 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
29230 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
29240 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
29250 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
29260 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
29270 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
29280 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
29290 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
292a0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
292b0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
292c0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
292d0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
292e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
292f0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
29300 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
29310 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
29320 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
29330 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
29340 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29350 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
29360 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
29370 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
29380 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
29390 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
293a0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
293b0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
293c0 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
293d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
293e0 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
293f0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
29400 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
29410 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
29420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29430 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
29440 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
29450 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29460 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
29470 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
29480 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
29490 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
294a0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
294b0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
294c0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
294d0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
294e0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
294f0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
29500 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
29510 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
29520 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
29530 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
29540 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
29550 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
29560 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
29570 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
29580 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
29590 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
295a0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
295b0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
295c0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
295d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
295e0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
295f0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
29600 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
29610 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
29620 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
29630 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
29640 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
29650 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
29660 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
29670 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
29680 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
29690 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
296a0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
296b0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
296c0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
296d0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
296e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
296f0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
29700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
29710 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
29720 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
29730 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
29740 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
29750 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
29760 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
29770 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
29780 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
29790 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
297a0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
297b0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
297c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
297d0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
297e0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
297f0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
29800 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
29810 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
29820 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
29830 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
29840 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
29850 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
29860 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
29870 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
29880 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
29890 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
298a0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
298b0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
298c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
298d0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
298e0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
298f0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
29900 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
29910 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
29920 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
29930 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
29940 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29950 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
29960 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
29970 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
29980 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
29990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
299a0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
299b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
299c0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
299d0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
299e0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
299f0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
29a00 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
29a10 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
29a20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
29a30 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
29a40 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
29a50 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
29a60 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
29a70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
29a80 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
29a90 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29aa0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29ab0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29ac0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
29ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29ae0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29af0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
29b00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29b10 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
29b20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
29b30 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
29b40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
29b50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29b60 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
29b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29b80 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
29b90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29ba0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
29bb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29bc0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
29bd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
29be0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
29bf0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
29c00 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
29c10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29c20 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
29c30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
29c40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
29c50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29c60 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
29c70 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
29c80 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
29c90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
29ca0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29cb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
29cc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29cd0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
29ce0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
29cf0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
29d00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
29d10 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
29d20 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29d30 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
29d40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
29d50 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
29d60 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
29d70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
29d80 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
29d90 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
29da0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
29db0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
29dc0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
29dd0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
29de0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
29df0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
29e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29e10 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
29e20 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
29e30 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
29e40 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
29e50 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
29e60 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
29e70 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
29e80 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
29e90 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
29ea0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
29eb0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
29ec0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
29ed0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
29ee0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
29ef0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
29f00 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
29f10 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
29f20 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
29f30 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
29f40 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
29f50 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
29f60 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
29f70 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
29f80 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
29f90 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
29fa0 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
29fb0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
29fc0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
29fd0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
29fe0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
29ff0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2a000 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2a010 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a020 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2a030 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2a040 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a050 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2a060 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a070 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a080 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2a090 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2a0a0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2a0b0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2a0c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a0d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a0e0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
2a0f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2a100 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2a110 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
2a120 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
2a130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a140 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
2a150 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2a160 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
2a170 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2a180 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
2a190 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
2a1a0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
2a1b0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2a1c0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2a1d0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
2a1e0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
2a1f0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
2a200 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
2a210 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
2a220 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
2a230 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
2a240 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
2a250 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2a260 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
2a270 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
2a280 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
2a290 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
2a2a0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
2a2b0 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
2a2c0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
2a2d0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
2a2e0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2a2f0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
2a300 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
2a310 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
2a320 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
2a330 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
2a340 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
2a350 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
2a360 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
2a370 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2a380 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
2a390 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
2a3a0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
2a3b0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
2a3c0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
2a3d0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
2a3e0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
2a3f0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
2a400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a410 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2a420 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2a430 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2a440 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2a450 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a460 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2a470 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2a480 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a490 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2a4a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2a4b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
2a4c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a4d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a4e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2a4f0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2a500 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2a510 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2a520 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2a530 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2a540 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2a550 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2a560 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2a570 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2a580 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2a590 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2a5a0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2a5b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2a5c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2a5d0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2a5e0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2a5f0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2a600 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2a610 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2a620 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2a630 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2a640 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2a650 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2a660 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2a670 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2a680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a690 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2a6a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a6b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2a6c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2a6d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a6e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a6f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2a700 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a710 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2a720 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2a730 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a740 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
2a750 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
2a760 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
2a770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2a780 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
2a790 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
2a7a0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
2a7b0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2a7c0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2a7d0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2a7e0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2a7f0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2a800 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2a810 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2a820 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a830 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2a840 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2a850 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2a860 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2a870 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2a880 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2a890 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2a8a0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2a8b0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2a8c0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2a8d0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2a8e0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2a8f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a900 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2a910 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a920 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2a930 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2a940 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a950 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2a960 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2a970 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2a980 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2a990 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2a9a0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2a9b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a9c0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2a9d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a9e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2a9f0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2aa00 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2aa10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2aa20 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2aa30 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2aa40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2aa50 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2aa60 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2aa70 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2aa80 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2aa90 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2aaa0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2aab0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2aac0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2aad0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2aae0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2aaf0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2ab00 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2ab10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ab20 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2ab30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2ab40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2ab50 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2ab60 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2ab70 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2ab80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ab90 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2aba0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2abb0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2abc0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2abd0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2abe0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2abf0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2ac00 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2ac10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2ac20 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2ac30 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2ac40 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2ac50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac60 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2ac70 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2ac80 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2ac90 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2aca0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2acb0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2acc0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2acd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2ace0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2acf0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2ad00 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2ad10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2ad20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2ad30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2ad40 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2ad50 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2ad60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2ad70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2ad80 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2ad90 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2ada0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2adb0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2adc0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2add0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2ade0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2adf0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2ae00 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2ae10 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2ae20 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2ae30 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2ae40 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2ae50 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2ae60 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2ae70 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2ae80 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2ae90 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2aea0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2aeb0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2aec0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2aed0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2aee0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2aef0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
2af00 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2af10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2af20 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2af30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2af40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2af50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2af60 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2af70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2af80 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2af90 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2afa0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2afb0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
2afc0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2afd0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2afe0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2aff0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2b000 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2b010 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2b020 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2b030 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2b040 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2b050 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2b060 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2b070 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2b080 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2b090 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2b0a0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2b0b0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2b0c0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2b0d0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2b0e0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2b0f0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2b100 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2b110 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2b120 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2b130 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2b140 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2b150 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2b160 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2b170 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2b180 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2b190 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2b1a0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2b1b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b1c0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2b1d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b1e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2b1f0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2b200 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2b210 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b220 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2b230 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2b240 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2b250 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2b260 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2b270 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2b280 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2b290 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2b2a0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2b2b0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2b2c0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2b2d0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2b2e0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2b2f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2b300 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2b310 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2b320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b330 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2b340 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2b350 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2b360 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2b370 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2b380 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2b390 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2b3a0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2b3b0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2b3c0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2b3d0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2b3e0 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2b3f0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2b400 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2b410 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2b420 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2b430 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2b440 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2b450 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2b460 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2b470 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2b480 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2b490 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2b4a0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2b4b0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2b4c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2b4d0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2b4e0 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2b4f0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2b500 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2b510 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2b520 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2b530 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2b540 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2b550 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2b560 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2b570 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2b580 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2b590 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2b5a0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2b5b0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2b5c0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2b5d0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2b5e0 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2b5f0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2b600 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2b610 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2b620 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2b630 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2b640 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2b650 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2b660 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2b670 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2b680 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2b690 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2b6a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2b6b0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2b6c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b6d0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2b6e0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2b6f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2b700 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2b710 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2b720 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2b730 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2b740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2b750 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2b760 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2b770 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2b780 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2b790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b7a0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2b7b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2b7c0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2b7d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2b7e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
2b7f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2b800 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b810 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2b820 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b830 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2b840 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2b850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2b860 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2b870 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b880 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b890 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2b8a0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2b8b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b8c0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2b8d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b8e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2b8f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2b900 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2b910 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2b920 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b930 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2b940 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b950 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2b960 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b970 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2b980 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b990 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2b9a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2b9b0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2b9c0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2b9d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2b9e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2b9f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ba00 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2ba10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2ba20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2ba30 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2ba40 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2ba50 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2ba60 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2ba70 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2ba80 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2ba90 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2baa0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2bab0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2bac0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2bad0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2bae0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2baf0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2bb00 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2bb10 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2bb20 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2bb30 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2bb40 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2bb50 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2bb60 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2bb70 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2bb80 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2bb90 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2bba0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2bbb0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2bbc0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2bbd0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2bbe0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2bbf0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2bc00 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2bc10 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2bc20 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2bc30 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2bc40 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2bc50 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2bc60 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2bc70 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2bc80 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2bc90 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2bca0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2bcb0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2bcc0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2bcd0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2bce0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2bcf0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2bd00 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2bd10 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2bd20 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2bd30 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2bd40 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2bd50 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2bd60 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2bd70 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2bd80 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2bd90 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2bda0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2bdb0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2bdc0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2bdd0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2bde0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2bdf0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2be00 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2be10 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2be20 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
2be30 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2be40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2be50 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
2be60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2be70 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2be80 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2be90 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2bea0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2beb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bec0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2bed0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
2bee0 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2bef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bf00 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2bf10 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2bf20 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2bf30 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2bf40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bf50 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2bf60 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2bf70 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2bf80 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2bf90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bfa0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2bfb0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2bfc0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2bfd0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2bfe0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2bff0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2c000 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2c010 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2c020 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2c030 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2c040 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2c050 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2c060 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2c070 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2c080 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2c090 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2c0a0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2c0b0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2c0c0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2c0d0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2c0e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2c0f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2c100 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2c110 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2c120 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2c130 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2c140 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2c150 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2c160 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2c170 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2c180 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2c190 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2c1a0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2c1b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2c1c0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2c1d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2c1e0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2c1f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2c200 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2c210 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2c220 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2c230 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2c240 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2c250 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2c260 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2c270 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2c280 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2c290 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2c2a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2c2b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2c2c0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2c2d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2c2e0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2c2f0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2c300 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2c310 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2c320 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2c330 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2c340 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2c350 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2c360 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2c370 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2c380 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2c390 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2c3a0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2c3b0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2c3c0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2c3d0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2c3e0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2c3f0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2c400 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2c410 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2c420 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2c430 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2c440 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2c450 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2c460 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2c470 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2c480 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2c490 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2c4a0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2c4b0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2c4c0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2c4d0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2c4e0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2c4f0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2c500 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2c510 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2c520 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2c530 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2c540 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2c550 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2c560 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2c570 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2c580 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2c590 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2c5a0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2c5b0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2c5c0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2c5d0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2c5e0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2c5f0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2c600 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2c610 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2c620 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2c630 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2c640 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2c650 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2c660 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2c670 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2c680 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2c690 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2c6a0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2c6b0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2c6c0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2c6d0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2c6e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2c6f0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2c700 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2c710 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2c720 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2c730 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2c740 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2c750 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2c760 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2c770 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2c780 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2c790 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2c7a0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2c7b0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2c7c0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c7d0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2c7e0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c7f0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2c800 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c810 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2c820 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2c830 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2c840 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2c850 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2c860 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2c870 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2c880 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2c890 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2c8a0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2c8b0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2c8c0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2c8d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2c8e0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2c8f0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2c900 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2c910 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2c920 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2c930 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2c940 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2c950 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2c960 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2c970 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2c980 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2c990 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2c9a0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2c9b0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2c9c0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2c9d0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2c9e0 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2c9f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2ca00 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2ca10 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2ca20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2ca30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2ca40 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2ca50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ca60 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2ca70 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2ca80 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2ca90 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2caa0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2cab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2cac0 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2cad0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2cae0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2caf0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2cb00 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2cb10 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2cb20 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2cb30 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2cb40 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2cb50 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2cb60 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2cb70 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2cb80 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2cb90 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2cba0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2cbb0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2cbc0 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2cbd0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2cbe0 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2cbf0 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2cc00 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2cc10 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2cc20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2cc30 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2cc40 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2cc50 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2cc60 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2cc70 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2cc80 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2cc90 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2cca0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2ccb0 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2ccc0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2ccd0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2cce0 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2ccf0 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2cd00 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2cd10 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2cd20 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2cd30 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2cd40 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2cd50 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2cd60 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2cd70 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2cd80 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2cd90 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2cda0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2cdb0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2cdc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2cdd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cde0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2cdf0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2ce00 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2ce10 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2ce20 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2ce30 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2ce40 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2ce50 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2ce60 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2ce70 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2ce80 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2ce90 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2cea0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2ceb0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2cec0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2ced0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2cee0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2cef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cf00 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2cf10 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2cf20 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2cf30 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2cf40 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2cf50 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2cf60 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2cf70 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2cf80 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2cf90 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2cfa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2cfb0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2cfc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2cfd0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2cfe0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2cff0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2d000 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2d010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2d020 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d030 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2d040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d050 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2d060 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d070 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2d080 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2d090 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2d0a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2d0b0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2d0c0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2d0d0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2d0e0 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2d0f0 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2d100 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2d110 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2d120 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2d130 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2d140 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2d150 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2d160 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2d170 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2d180 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2d190 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d1a0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2d1b0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2d1c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2d1d0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2d1e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d1f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d200 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2d210 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2d220 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2d230 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d240 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2d250 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d260 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2d270 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2d280 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2d290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2d2a0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2d2b0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2d2c0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2d2d0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2d2e0 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2d2f0 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2d300 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2d310 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2d320 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2d330 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2d340 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2d350 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2d360 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2d370 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2d380 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2d390 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74   int sqlite3_dat
2d3a0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2d3b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2d3c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2d3d0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2d3e0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2d3f0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2d400 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2d410 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2d420 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2d430 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2d440 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2d450 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2d460 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2d470 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2d480 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2d490 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2d4a0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2d4b0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2d4c0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2d4d0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2d4e0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2d4f0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2d500 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2d510 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2d520 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2d530 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2d540 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2d550 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2d560 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2d570 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2d580 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2d590 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2d5a0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2d5b0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2d5c0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2d5d0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2d5e0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2d5f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2d600 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2d610 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2d620 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2d630 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2d640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2d650 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2d660 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2d670 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2d680 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2d690 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2d6a0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2d6b0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2d6c0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2d6d0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2d6e0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2d6f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2d700 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2d710 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2d720 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2d730 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2d740 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2d750 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2d760 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2d770 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2d780 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2d790 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2d7a0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2d7b0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2d7c0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2d7d0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2d7e0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2d7f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d800 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2d810 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2d820 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2d830 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2d840 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2d850 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d860 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2d870 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2d880 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2d890 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2d8a0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2d8b0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2d8c0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2d8d0 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2d8e0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2d8f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2d900 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2d910 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2d920 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2d930 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2d940 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2d950 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2d960 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2d970 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2d980 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2d990 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2d9a0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2d9b0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2d9c0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2d9d0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2d9e0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2d9f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2da00 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2da10 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2da20 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2da30 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2da40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2da50 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2da60 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2da70 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2da80 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2da90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2daa0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2dab0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2dac0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2dad0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2dae0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2daf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2db00 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2db10 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2db20 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2db30 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2db40 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2db50 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2db60 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2db70 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2db80 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2db90 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2dba0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2dbb0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2dbc0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2dbd0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2dbe0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2dbf0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2dc00 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2dc10 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2dc20 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2dc30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2dc40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2dc50 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2dc60 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2dc70 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2dc80 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2dc90 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2dca0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2dcb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2dcc0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2dcd0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2dce0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2dcf0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2dd00 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2dd10 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2dd20 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2dd30 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2dd40 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2dd50 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2dd60 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2dd70 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2dd80 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2dd90 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2dda0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2ddb0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2ddc0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2ddd0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2dde0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ddf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2de00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2de10 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2de20 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2de30 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2de40 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2de50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2de60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2de70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2de80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2de90 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2dea0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2deb0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2dec0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2ded0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2dee0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2def0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2df00 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2df10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2df20 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2df30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2df40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2df50 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2df60 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2df70 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2df80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2df90 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2dfa0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2dfb0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2dfc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dfd0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2dfe0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2dff0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2e000 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2e010 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2e020 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2e030 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e040 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2e050 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e060 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2e070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e080 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2e090 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2e0a0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2e0b0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2e0c0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2e0d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e0e0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2e0f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2e100 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e110 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2e120 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2e130 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2e140 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2e150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e160 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2e170 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2e180 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2e190 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2e1a0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2e1b0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e1c0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2e1d0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2e1e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e1f0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2e200 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2e210 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2e220 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2e230 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2e240 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2e250 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e260 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2e270 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2e280 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2e290 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e2a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2e2b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2e2c0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2e2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e2e0 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2e2f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e300 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2e310 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2e320 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2e330 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2e340 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2e350 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2e360 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2e370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e380 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2e390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e3a0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2e3b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2e3c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2e3d0 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2e3e0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2e3f0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2e400 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2e410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e420 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2e430 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e440 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2e450 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2e460 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2e470 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2e480 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2e490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e4a0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2e4b0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2e4c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2e4d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2e4e0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2e4f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2e500 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2e510 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2e520 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e530 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2e540 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e550 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2e560 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2e570 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2e580 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2e590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2e5a0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2e5b0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2e5c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e5d0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2e5e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e5f0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2e600 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2e610 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2e620 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2e630 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2e640 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2e650 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e660 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2e670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2e680 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2e690 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2e6a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2e6b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2e6c0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2e6d0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2e6e0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2e6f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2e700 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2e710 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2e720 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2e730 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2e740 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2e750 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2e760 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2e770 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2e780 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2e790 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2e7a0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2e7b0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2e7c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2e7d0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2e7e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2e7f0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2e800 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2e810 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2e820 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2e830 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2e840 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2e850 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2e860 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2e870 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2e880 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2e890 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2e8a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2e8b0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2e8c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2e8d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2e8e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2e8f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e900 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e910 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2e920 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2e930 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e940 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2e950 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2e960 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2e970 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2e980 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2e990 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2e9a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e9b0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2e9c0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2e9d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2e9e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2e9f0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2ea00 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2ea10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2ea20 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2ea30 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2ea40 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2ea50 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2ea60 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2ea70 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2ea80 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2ea90 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2eaa0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2eab0 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
2eac0 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
2ead0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2eae0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2eaf0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2eb00 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2eb10 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2eb20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
2eb30 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
2eb40 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2eb50 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2eb60 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2eb70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2eb80 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2eb90 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
2eba0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
2ebb0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2ebc0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2ebd0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
2ebe0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
2ebf0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2ec00 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2ec10 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2ec20 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2ec30 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2ec40 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2ec50 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2ec60 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2ec70 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2ec80 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2ec90 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2eca0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2ecb0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2ecc0 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2ecd0 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2ece0 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2ecf0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2ed00 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2ed10 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2ed20 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2ed30 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2ed40 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2ed50 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2ed60 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2ed70 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2ed80 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2ed90 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2eda0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2edb0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2edc0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2edd0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2ede0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2edf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2ee00 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2ee10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ee20 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2ee30 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2ee40 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2ee50 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2ee60 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2ee70 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2ee80 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2ee90 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2eea0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2eeb0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2eec0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eed0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2eee0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2eef0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2ef00 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2ef10 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2ef20 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2ef30 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2ef40 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2ef50 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2ef60 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2ef70 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2ef80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ef90 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2efa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2efb0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2efc0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2efd0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2efe0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2eff0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2f000 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2f010 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2f020 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2f030 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2f040 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2f050 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2f060 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2f070 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2f080 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2f090 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2f0a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2f0b0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2f0c0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2f0d0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2f0e0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2f0f0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2f100 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2f110 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2f120 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2f130 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2f140 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2f150 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2f160 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2f170 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2f180 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2f190 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2f1a0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2f1b0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2f1c0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2f1d0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2f1e0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2f1f0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2f200 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2f210 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2f220 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2f230 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2f240 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2f250 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2f260 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2f270 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2f280 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2f290 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2f2a0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2f2b0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2f2c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f2d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2f2e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2f2f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2f300 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2f310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f320 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2f330 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f340 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2f350 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2f360 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2f370 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2f380 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2f390 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2f3a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f3b0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2f3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2f3d0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2f3e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2f3f0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2f400 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2f410 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2f420 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2f430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f440 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2f450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f460 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2f470 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2f480 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2f490 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2f4a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f4b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2f4c0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2f4d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2f4e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f4f0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2f500 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2f510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f520 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2f530 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2f540 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2f550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2f560 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2f570 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2f580 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2f590 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2f5a0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2f5b0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2f5c0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2f5d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2f5e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2f5f0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2f600 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2f610 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2f620 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2f630 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2f640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2f650 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2f660 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2f670 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
2f680 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f690 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2f6a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f6b0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
2f6c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2f6d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
2f6e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2f6f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2f700 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2f710 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2f720 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2f730 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2f740 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2f750 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2f760 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2f770 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2f780 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2f790 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2f7a0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2f7b0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2f7c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2f7d0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2f7e0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2f7f0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53  E_NOMEM].)^.*/.S
2f800 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f810 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2f820 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2f830 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f840 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2f850 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f860 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2f870 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f880 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2f890 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f8a0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2f8b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f8c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
2f8d0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2f8e0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2f8f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f900 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2f910 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f920 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2f930 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f940 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2f950 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2f960 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2f970 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f980 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2f990 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
2f9a0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2f9b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2f9c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f9d0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2f9e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2f9f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fa00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2fa10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2fa20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2fa30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2fa40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fa50 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2fa60 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
2fa70 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2fa80 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2fa90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2faa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fab0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2fac0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2fad0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2fae0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2faf0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2fb00 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2fb10 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2fb20 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2fb30 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2fb40 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2fb50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2fb60 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2fb70 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2fb80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2fb90 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2fba0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2fbb0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2fbc0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2fbd0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2fbe0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2fbf0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2fc00 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2fc10 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2fc20 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2fc30 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2fc40 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2fc50 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2fc60 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2fc70 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2fc80 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2fc90 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2fca0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2fcb0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2fcc0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2fcd0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2fce0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2fcf0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2fd00 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2fd10 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2fd20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2fd30 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2fd40 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2fd50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fd60 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2fd70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2fd80 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2fd90 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2fda0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2fdb0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2fdc0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2fdd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2fde0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2fdf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2fe00 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2fe10 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2fe20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fe30 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2fe40 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2fe50 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2fe60 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2fe70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fe80 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2fe90 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2fea0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2feb0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2fec0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2fed0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2fee0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2fef0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2ff00 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2ff10 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2ff20 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2ff30 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2ff40 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2ff50 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2ff60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ff70 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2ff80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2ff90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2ffa0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2ffb0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ffc0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2ffd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ffe0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2fff0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
30000 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30010 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
30020 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
30030 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
30040 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
30050 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
30060 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
30070 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
30080 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
30090 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
300a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
300b0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
300c0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
300d0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
300e0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
300f0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
30100 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
30110 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
30120 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
30130 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
30140 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
30150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30160 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
30170 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
30180 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
30190 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
301a0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
301b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
301c0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
301d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
301e0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
301f0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
30200 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
30210 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
30220 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
30230 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
30240 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
30250 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30260 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
30270 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
30280 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30290 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
302a0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
302b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
302c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
302d0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
302e0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
302f0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
30300 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
30310 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
30320 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
30330 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
30340 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
30350 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
30360 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
30370 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30380 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
30390 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
303a0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
303b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
303c0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
303d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
303e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
303f0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
30400 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
30410 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
30420 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
30430 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
30440 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
30450 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
30470 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
30480 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
304a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
304b0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
304c0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
304d0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
304e0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
304f0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
30500 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
30510 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
30520 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
30530 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
30540 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
30550 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
30560 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
30570 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
30580 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
30590 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
305a0 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
305b0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
305c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
305d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
305e0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
305f0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
30600 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
30610 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
30620 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
30630 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
30640 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
30650 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
30660 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
30670 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30680 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
30690 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
306a0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
306b0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
306c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
306d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
306e0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
306f0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
30700 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
30710 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
30720 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
30730 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
30740 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
30750 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
30760 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
30770 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
30780 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30790 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
307a0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
307b0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
307c0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
307d0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
307e0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
307f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
30800 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
30810 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
30820 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
30830 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
30840 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
30850 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
30860 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
30870 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
30880 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
30890 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
308a0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
308b0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
308c0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
308d0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
308e0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
308f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
30900 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
30910 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
30920 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
30930 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
30940 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
30950 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
30960 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
30970 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
30980 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
30990 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
309a0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
309b0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
309c0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
309d0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
309e0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
309f0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
30a00 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
30a10 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
30a20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
30a30 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
30a40 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
30a50 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
30a60 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30a70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
30a80 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
30a90 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
30aa0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
30ab0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
30ac0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
30ad0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
30ae0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
30af0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
30b00 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
30b10 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
30b20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
30b30 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
30b40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30b50 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
30b60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30b70 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
30b80 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
30b90 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
30ba0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
30bb0 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
30bc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30bd0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
30be0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
30bf0 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
30c00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30c10 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
30c20 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
30c30 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
30c40 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
30c50 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
30c60 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
30c70 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
30c80 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
30c90 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
30ca0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
30cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
30cc0 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
30cd0 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
30ce0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
30cf0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
30d00 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
30d10 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
30d20 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
30d30 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
30d40 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
30d50 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
30d60 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
30d70 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
30d80 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
30d90 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
30da0 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
30db0 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
30dc0 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
30dd0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
30de0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
30df0 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
30e00 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
30e10 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
30e20 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
30e30 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
30e40 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
30e50 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
30e60 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
30e70 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
30e80 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
30e90 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
30ea0 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
30eb0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
30ec0 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
30ed0 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
30ee0 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
30ef0 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
30f00 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
30f10 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
30f20 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
30f30 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
30f40 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
30f50 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
30f60 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
30f70 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
30f80 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
30f90 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
30fa0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
30fb0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
30fc0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
30fd0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
30fe0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
30ff0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
31000 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
31010 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
31020 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
31030 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
31040 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
31050 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
31060 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
31070 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
31080 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
31090 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
310a0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
310b0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
310c0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
310d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
310e0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
310f0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
31100 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
31110 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
31120 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
31130 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
31140 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
31150 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
31160 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
31170 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
31180 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
31190 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
311a0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
311b0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
311c0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
311d0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
311e0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
311f0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
31200 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
31210 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
31220 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
31230 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
31240 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
31250 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
31260 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
31270 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
31280 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
31290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
312a0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
312b0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
312c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
312d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
312e0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
312f0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
31300 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
31310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
31320 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
31330 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
31340 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
31350 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
31360 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
31370 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
31380 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
31390 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
313a0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
313b0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
313c0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
313d0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
313e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
313f0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
31400 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
31410 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
31420 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
31430 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
31440 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
31450 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31460 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
31470 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
31480 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
31490 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
314a0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
314b0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
314c0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
314d0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
314e0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
314f0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
31500 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
31510 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31520 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
31530 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
31540 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
31550 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
31560 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
31570 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
31580 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
31590 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
315a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
315b0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
315c0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
315d0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
315e0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
315f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
31600 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
31610 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
31620 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
31630 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
31640 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
31650 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
31660 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
31670 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
31680 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
31690 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
316a0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
316b0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
316c0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
316d0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
316e0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
316f0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
31700 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
31710 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
31720 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
31730 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
31740 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
31750 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
31760 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
31770 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
31780 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
31790 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
317a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
317b0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
317c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
317d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
317e0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
317f0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
31800 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
31810 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
31820 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
31830 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
31840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
31850 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
31860 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
31870 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
31880 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
31890 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
318a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
318b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
318c0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
318d0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
318e0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
318f0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
31900 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
31910 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
31920 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
31930 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31940 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31950 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31960 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
31970 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
31980 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
31990 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
319a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
319b0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
319c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
319d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
319e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
319f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
31a00 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
31a10 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
31a20 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
31a30 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
31a40 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
31a50 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31a60 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31a70 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
31a80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31a90 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31aa0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
31ab0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
31ac0 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
31ad0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31ae0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
31af0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
31b00 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
31b10 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
31b20 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
31b30 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
31b40 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
31b50 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
31b60 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31b80 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31b90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31ba0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31bb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31bc0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
31bd0 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
31be0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
31bf0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
31c00 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
31c10 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
31c20 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
31c30 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
31c40 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
31c50 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
31c60 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
31c70 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
31c80 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
31c90 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
31ca0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
31cb0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
31cc0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
31cd0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
31ce0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
31cf0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
31d00 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
31d10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
31d20 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
31d30 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
31d40 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
31d50 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
31d60 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
31d70 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
31d80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31d90 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
31da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31db0 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
31dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
31dd0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
31de0 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
31df0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
31e00 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
31e10 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
31e20 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
31e30 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
31e40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31e50 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
31e60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31e70 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
31e80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31e90 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
31ea0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31eb0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
31ec0 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
31ed0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
31ee0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
31ef0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
31f00 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
31f10 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
31f20 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
31f30 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
31f40 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
31f50 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
31f60 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
31f70 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
31f80 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
31f90 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
31fa0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
31fb0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
31fc0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
31fd0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
31fe0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
31ff0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
32000 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
32010 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
32020 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
32030 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
32040 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
32050 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
32060 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
32070 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
32080 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
32090 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
320a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
320b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
320c0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
320d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
320e0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
320f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
32100 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32110 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
32120 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
32130 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
32140 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
32150 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
32160 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32170 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
32180 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
32190 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
321a0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
321b0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
321c0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
321d0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
321e0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
321f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
32200 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
32210 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
32220 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
32230 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
32240 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
32250 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
32260 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
32270 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
32280 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
32290 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
322a0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
322b0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
322c0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
322d0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
322e0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
322f0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
32300 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
32310 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
32320 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
32330 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
32340 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
32350 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
32360 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
32370 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
32380 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
32390 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
323a0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
323b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
323c0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
323d0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
323e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
323f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
32400 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
32410 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
32420 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
32430 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
32440 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
32450 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
32460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
32470 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
32480 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
32490 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
324a0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
324b0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
324c0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
324d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
324e0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
324f0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
32500 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
32510 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
32520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
32530 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
32540 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32550 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
32560 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
32570 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
32580 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
32590 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
325a0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
325b0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
325c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
325d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
325e0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
325f0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
32600 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
32610 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
32620 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
32630 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32640 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
32650 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32660 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
32670 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
32680 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
32690 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
326a0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
326b0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
326c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
326d0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
326e0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
326f0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
32700 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
32710 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
32720 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
32730 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
32740 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32750 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
32760 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
32770 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
32780 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
32790 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
327a0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
327b0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
327c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
327d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
327e0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
327f0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
32800 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
32810 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
32820 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
32830 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
32840 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
32850 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
32860 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
32870 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
32880 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
32890 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
328a0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
328b0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
328c0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
328d0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
328e0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
328f0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
32900 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
32910 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
32920 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
32930 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
32940 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
32950 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
32960 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
32970 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
32980 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
32990 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
329a0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
329b0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
329c0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
329d0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
329e0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
329f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
32a00 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
32a10 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
32a20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
32a30 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
32a40 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
32a50 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
32a60 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
32a70 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
32a80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
32a90 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
32aa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32ab0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
32ac0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32ad0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
32ae0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
32af0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
32b00 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32b10 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
32b20 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
32b30 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
32b40 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
32b50 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ters..*/.SQLITE_
32b60 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
32b70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
32b80 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
32b90 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
32ba0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
32bb0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
32bc0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
32bd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
32be0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
32bf0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
32c00 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
32c10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
32c20 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
32c30 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32c40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
32c50 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
32c60 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
32c70 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
32c80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
32c90 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
32ca0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32cb0 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
32cc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
32cd0 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
32ce0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
32cf0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
32d00 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
32d10 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
32d20 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
32d30 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
32d40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32d50 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
32d60 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
32d70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
32d80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32d90 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
32da0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
32db0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
32dc0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
32dd0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
32de0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
32df0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
32e00 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
32e10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32e20 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
32e30 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
32e40 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
32e50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
32e60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
32e70 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
32e80 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
32e90 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
32ea0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
32eb0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
32ec0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
32ed0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32ee0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
32ef0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
32f00 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
32f10 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
32f20 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
32f30 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
32f40 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
32f50 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
32f60 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
32f70 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
32f80 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
32f90 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
32fa0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
32fb0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
32fc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32fd0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
32fe0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
32ff0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
33000 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
33010 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
33020 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33030 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
33040 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
33050 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
33060 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
33070 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
33080 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
33090 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
330a0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
330b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
330c0 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
330d0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
330e0 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
330f0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
33100 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
33110 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
33120 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
33130 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
33140 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
33150 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
33160 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
33170 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
33180 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
33190 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
331a0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
331b0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
331c0 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
331d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
331e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
331f0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
33200 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
33210 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
33220 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
33230 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
33240 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
33250 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
33260 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
33270 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
33280 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
33290 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
332a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
332b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
332c0 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
332d0 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
332e0 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
332f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
33300 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
33310 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
33320 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
33330 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33340 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
33350 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
33360 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
33370 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
33380 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
33390 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
333a0 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
333b0 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
333c0 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
333d0 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
333e0 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
333f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33400 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
33410 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
33420 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
33430 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
33440 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
33450 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
33460 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
33470 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
33480 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33490 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
334a0 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
334b0 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
334c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
334d0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
334e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
334f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
33500 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
33510 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
33520 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
33530 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
33540 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
33550 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
33560 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
33570 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
33580 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
33590 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
335a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
335b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
335c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
335d0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
335e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
335f0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
33600 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
33610 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33620 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
33630 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
33640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33650 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
33660 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
33670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
33680 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
33690 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
336a0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
336b0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
336c0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
336d0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
336e0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
336f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
33700 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33710 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
33720 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33730 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
33740 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
33750 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33760 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33770 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33780 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33790 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
337a0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
337b0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
337c0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
337d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
337e0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
337f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
33800 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
33810 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33820 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33830 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
33840 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
33850 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
33860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33870 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
33880 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
33890 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
338a0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
338b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
338c0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
338d0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
338e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
338f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33900 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33910 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33920 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33930 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
33940 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
33950 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33960 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33970 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33980 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
33990 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
339a0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
339b0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
339c0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
339d0 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
339e0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
339f0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
33a00 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
33a10 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
33a20 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
33a30 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
33a40 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
33a50 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
33a60 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
33a70 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
33a80 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
33a90 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
33aa0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
33ab0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
33ac0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
33ad0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
33ae0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
33af0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
33b00 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
33b10 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
33b20 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
33b30 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
33b40 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
33b50 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
33b60 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
33b70 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
33b80 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
33b90 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
33ba0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
33bb0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
33bc0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
33bd0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
33be0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
33bf0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
33c00 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
33c10 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
33c20 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
33c30 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
33c40 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
33c50 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
33c60 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
33c70 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
33c80 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
33c90 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
33ca0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
33cb0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
33cc0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
33cd0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33ce0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
33cf0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
33d00 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
33d10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33d20 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
33d30 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
33d40 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
33d50 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
33d60 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
33d70 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
33d80 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33d90 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
33da0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33dc0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33dd0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
33de0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
33df0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
33e00 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
33e10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33e20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33e30 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
33e40 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
33e50 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
33e60 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
33e70 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
33e80 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
33e90 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
33ea0 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
33eb0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
33ec0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
33ed0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
33ee0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
33ef0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
33f00 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
33f10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33f20 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
33f30 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
33f40 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
33f50 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
33f60 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
33f70 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
33f80 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
33f90 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
33fa0 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
33fb0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
33fc0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
33fd0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
33fe0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
33ff0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
34000 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
34010 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
34020 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
34030 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
34040 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
34050 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
34060 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
34070 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
34080 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
34090 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
340a0 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
340b0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
340c0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
340d0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
340e0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
340f0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
34100 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
34110 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
34120 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
34130 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
34140 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
34150 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
34160 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
34170 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
34180 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
34190 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
341a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
341b0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
341c0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
341d0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
341e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
341f0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
34200 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
34210 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
34220 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
34230 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
34240 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
34250 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
34260 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
34270 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
34280 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34290 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
342a0 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
342b0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
342c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
342d0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
342e0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
342f0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
34300 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
34310 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
34320 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
34330 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
34340 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
34350 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
34360 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
34370 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
34380 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
34390 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
343a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
343b0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
343c0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
343d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
343e0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
343f0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
34400 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
34410 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
34420 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
34430 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
34440 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34450 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
34460 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  I void sqlite3_s
34470 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
34480 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34490 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
344a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
344b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
344c0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
344d0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
344e0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
344f0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
34500 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
34510 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
34520 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
34530 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
34540 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
34550 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
34560 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34570 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
34580 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
34590 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
345a0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
345b0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
345c0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
345d0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
345e0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
345f0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
34600 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
34610 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
34620 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
34630 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
34640 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
34650 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
34660 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
34670 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
34680 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
34690 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
346a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
346b0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
346c0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
346d0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
346e0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
346f0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
34700 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
34710 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
34720 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
34730 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
34740 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
34750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
34760 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
34770 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
34780 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
34790 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
347a0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
347b0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
347c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
347d0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
347e0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
347f0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
34800 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
34810 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
34820 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
34830 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
34840 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
34850 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
34860 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
34870 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34880 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
34890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
348a0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
348b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
348c0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
348d0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
348e0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
348f0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
34900 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
34910 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
34920 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
34930 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
34940 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
34950 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
34960 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
34970 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
34980 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
34990 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
349a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
349b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
349c0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
349d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
349e0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
349f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
34a00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34a10 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
34a20 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
34a30 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
34a40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
34a50 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
34a60 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
34a70 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
34a80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
34ab0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
34ac0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
34ad0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
34ae0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34af0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
34b00 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
34b10 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
34b20 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
34b30 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
34b40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
34b50 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34b60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34b70 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
34b80 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
34b90 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
34ba0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
34bb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34bc0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
34bd0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
34be0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
34bf0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
34c00 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
34c10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34c20 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
34c30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34c40 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
34c50 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
34c60 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
34c70 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
34c80 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
34c90 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
34ca0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
34cb0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
34cc0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
34cd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34ce0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
34cf0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
34d00 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
34d10 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
34d20 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
34d30 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
34d40 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
34d50 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
34d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34d70 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
34d80 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
34d90 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
34da0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34db0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
34dc0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
34dd0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
34de0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
34df0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
34e00 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
34e10 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
34e20 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
34e30 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
34e40 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
34e50 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
34e60 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
34e70 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34e80 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34e90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
34ea0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34eb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34ec0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
34ed0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34ee0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
34ef0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
34f00 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
34f10 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
34f20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
34f30 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
34f40 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
34f50 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
34f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34f70 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
34f80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34f90 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
34fa0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
34fb0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
34fc0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
34fd0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
34fe0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
34ff0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
35000 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
35010 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
35020 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
35030 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
35040 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
35050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35060 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
35070 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
35080 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
35090 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
350a0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
350b0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
350c0 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
350d0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
350e0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
350f0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
35100 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
35110 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35120 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
35130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35140 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
35150 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
35160 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
35170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35180 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
35190 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
351a0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
351b0 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
351c0 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
351d0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
351e0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
351f0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
35200 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35210 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
35220 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
35230 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
35240 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
35250 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
35260 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
35270 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
35280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35290 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
352a0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
352b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
352c0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
352d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
352e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
352f0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
35300 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
35310 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
35320 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
35330 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35340 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
35350 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
35360 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
35370 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35380 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35390 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
353a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
353b0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
353c0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
353d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
353e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
353f0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
35400 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
35410 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
35420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35430 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35440 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
35450 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35460 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
35470 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35480 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
35490 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
354a0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
354b0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
354c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
354d0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
354e0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
354f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35500 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
35510 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
35520 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
35530 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
35540 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
35550 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
35560 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
35570 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
35580 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
35590 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
355a0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
355b0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
355c0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
355d0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
355e0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
355f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
35600 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
35610 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35620 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35630 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35640 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
35650 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
35660 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
35670 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
35680 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35690 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
356a0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
356b0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
356c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
356d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
356e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
356f0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
35700 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
35710 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
35720 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
35730 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
35740 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
35750 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
35760 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
35770 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35780 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
35790 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
357a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
357b0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
357c0 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
357d0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
357e0 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
357f0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
35800 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
35810 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
35820 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
35830 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
35840 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
35850 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
35860 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
35870 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
35880 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
35890 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
358a0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
358b0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
358c0 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
358d0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
358e0 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
358f0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
35900 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
35910 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
35920 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
35930 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
35940 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
35950 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
35960 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35970 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
35980 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
35990 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
359a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
359b0 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
359c0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
359d0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
359e0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
359f0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
35a00 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
35a10 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
35a20 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
35a30 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
35a40 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
35a50 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
35a60 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
35a70 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
35a80 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
35a90 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
35aa0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
35ab0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
35ac0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
35ad0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
35ae0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
35af0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
35b00 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
35b10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
35b20 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
35b30 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
35b40 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
35b50 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
35b60 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
35b70 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
35b80 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
35b90 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
35ba0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
35bb0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
35bc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35bd0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
35be0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
35bf0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
35c00 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
35c10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
35c20 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
35c30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
35c40 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
35c50 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
35c60 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
35c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35c80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
35c90 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35ca0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
35cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35cc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35cd0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
35ce0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
35cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35d00 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
35d10 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
35d20 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
35d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35d40 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
35d50 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
35d60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
35d70 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
35d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
35d90 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
35da0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
35db0 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
35dc0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
35dd0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
35de0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
35df0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
35e00 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
35e10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
35e20 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
35e30 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
35e40 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
35e50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35e60 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
35e70 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
35e80 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
35e90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35ea0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
35eb0 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
35ec0 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
35ed0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35ee0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
35ef0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
35f00 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
35f10 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
35f20 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
35f30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35f40 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
35f50 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
35f60 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
35f70 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
35f80 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
35f90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
35fa0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35fb0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
35fc0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
35fd0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
35fe0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
35ff0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
36000 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
36010 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36020 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  *, double);.SQLI
36030 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36040 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36060 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
36070 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
36080 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
36090 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
360a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
360b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
360c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
360d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
360e0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
360f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36100 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36110 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36120 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
36130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
36140 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
36150 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36160 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
36170 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
36180 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
36190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
361a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
361b0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  ext*, int);.SQLI
361c0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
361d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
361e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
361f0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
36200 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
36210 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36220 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
36230 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
36240 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36250 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
36260 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36270 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36280 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
36290 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
362a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
362b0 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
362c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
362d0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
362e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
362f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36300 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36310 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
36320 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36330 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
36340 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
36350 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36360 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
36370 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36380 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36390 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
363a0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
363b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
363c0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
363d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
363e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
363f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
36400 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
36410 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
36420 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
36430 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36440 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
36450 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
36460 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
36470 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
36480 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
36490 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
364a0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
364b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
364c0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
364d0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
364e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
364f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
36500 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
36510 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
36520 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
36530 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
36540 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
36550 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36560 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
36570 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
36580 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
36590 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
365a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
365b0 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
365c0 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
365d0 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
365e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
365f0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
36600 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
36610 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
36620 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
36630 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
36640 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
36650 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
36660 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
36670 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
36680 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
36690 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
366a0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
366b0 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
366c0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
366d0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
366e0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
366f0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
36700 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
36710 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
36720 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
36730 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
36740 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
36750 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
36760 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
36770 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
36780 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
36790 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
367a0 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
367b0 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
367c0 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
367d0 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
367e0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
367f0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
36800 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
36810 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
36820 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
36830 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
36840 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
36850 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
36860 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
36870 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
36880 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
36890 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
368a0 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
368b0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
368c0 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
368d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
368e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
368f0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
36900 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
36910 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36920 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36930 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
36940 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
36950 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
36960 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
36970 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
36980 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
36990 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
369a0 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
369b0 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
369c0 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
369d0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
369e0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
369f0 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
36a00 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
36a10 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
36a20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
36a30 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36a40 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
36a50 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
36a60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36a70 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
36a80 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
36a90 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
36aa0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
36ab0 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
36ac0 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
36ad0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
36ae0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
36af0 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
36b00 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
36b10 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
36b20 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
36b30 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
36b40 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
36b50 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
36b60 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
36b70 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
36b80 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
36b90 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
36ba0 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
36bb0 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
36bc0 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
36bd0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
36be0 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
36bf0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
36c00 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
36c10 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
36c20 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
36c30 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
36c40 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
36c50 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
36c60 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
36c70 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
36c80 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
36c90 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
36ca0 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
36cb0 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
36cc0 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
36cd0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
36ce0 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
36cf0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
36d00 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
36d10 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
36d20 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
36d30 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
36d40 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36d50 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
36d60 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
36d70 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
36d80 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
36d90 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
36da0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
36db0 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
36dc0 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
36dd0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
36de0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
36df0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
36e00 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
36e10 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
36e20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
36e30 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
36e40 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
36e50 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
36e60 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
36e70 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
36e80 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36e90 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
36ea0 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
36eb0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
36ec0 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
36ed0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
36ee0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36ef0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36f00 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
36f10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36f20 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
36f30 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
36f40 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
36f50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
36f60 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
36f70 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36f80 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
36f90 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
36fa0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
36fb0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
36fc0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
36fd0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
36fe0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
36ff0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
37000 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
37010 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
37020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
37030 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
37040 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
37050 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
37060 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
37070 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
37080 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
37090 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
370a0 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
370b0 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
370c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
370d0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
370e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
370f0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
37100 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
37110 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
37120 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
37130 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
37140 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
37150 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37160 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
37170 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
37180 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
37190 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
371a0 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
371b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
371c0 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
371d0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
371e0 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
371f0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
37200 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
37210 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
37220 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
37230 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
37240 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
37250 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
37260 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37270 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
37280 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37290 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
372a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
372b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
372c0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
372d0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
372e0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
372f0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37300 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37310 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37320 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37330 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37340 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
37350 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
37360 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37370 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
37390 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
373a0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
373b0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
373c0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
373d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
373e0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
373f0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
37400 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
37410 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37420 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37430 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
37440 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
37450 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
37460 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37470 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37480 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37490 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
374a0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
374b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
374c0 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
374d0 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
374e0 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
374f0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
37500 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
37510 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
37520 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
37530 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
37540 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
37550 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
37560 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
37570 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
37580 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
37590 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
375a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
375b0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
375c0 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
375d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
375e0 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
375f0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
37600 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37610 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
37620 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
37630 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
37640 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
37650 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
37660 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
37670 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
37680 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
37690 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
376a0 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
376b0 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
376c0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
376d0 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
376e0 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
376f0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
37700 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
37710 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
37720 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
37730 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
37740 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
37750 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
37760 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
37770 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
37780 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
37790 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
377a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
377b0 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
377c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
377d0 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
377e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
377f0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
37800 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
37810 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
37820 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
37830 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
37840 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
37850 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
37860 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
37870 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
37880 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
37890 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
378a0 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
378b0 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
378c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
378d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
378e0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
378f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37900 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
37910 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
37920 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
37930 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
37940 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
37950 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37960 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
37970 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37980 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
37990 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
379a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
379b0 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
379c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
379d0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
379e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
379f0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
37a00 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
37a10 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
37a20 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53  onst char*).);.S
37a30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37a40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37a50 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
37a60 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
37a70 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
37a80 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
37a90 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
37aa0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
37ab0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
37ac0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
37ad0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
37ae0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
37af0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
37b00 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
37b10 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
37b20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
37b30 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
37b40 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
37b50 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
37b60 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
37b70 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
37b80 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
37b90 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37ba0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
37bb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
37bc0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
37bd0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
37be0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
37bf0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
37c00 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
37c10 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
37c20 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  I int sqlite3_ke
37c30 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
37c40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37c50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37c60 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
37c70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
37c80 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37c90 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
37ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
37cb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37cc0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37cd0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
37ce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
37cf0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
37d00 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
37d10 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
37d20 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
37d30 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
37d40 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
37d50 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
37d60 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
37d70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
37d80 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
37d90 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37da0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37db0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
37dc0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
37dd0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
37de0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
37df0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37e00 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
37e10 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37e20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37e30 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37e40 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37e50 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
37e60 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
37e70 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51  new key */.);.SQ
37e80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
37e90 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20  ite3_rekey_v2(. 
37ea0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
37eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37ec0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
37ed0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
37ee0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
37ef0 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  me,           /*
37f00 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   Name of the dat
37f10 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
37f20 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
37f30 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
37f40 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
37f50 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
37f60 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
37f70 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
37f80 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
37f90 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
37fa0 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
37fb0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
37fc0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
37fd0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
37fe0 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
37ff0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
38000 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
38010 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
38020 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
38030 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
38040 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
38050 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
38060 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
38070 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
38080 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
38090 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
380a0 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
380b0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
380c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
380d0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
380e0 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
380f0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
38100 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
38110 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
38120 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
38130 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
38140 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
38150 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
38160 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
38170 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
38180 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
38190 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
381a0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
381b0 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
381c0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
381d0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
381e0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
381f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
38200 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
38210 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
38220 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
38230 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
38240 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
38250 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
38260 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
38270 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
38280 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
38290 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
382a0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
382b0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
382c0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
382d0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
382e0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
382f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
38300 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
38310 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
38320 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
38330 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
38340 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
38350 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
38360 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
38370 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
38380 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
38390 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
383a0 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
383b0 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
383c0 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
383d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
383e0 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
383f0 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
38400 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
38410 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
38420 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
38430 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38440 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
38450 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
38460 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
38470 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
38480 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
38490 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
384a0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
384b0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
384c0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
384d0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
384e0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
384f0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
38500 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
38510 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
38520 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
38530 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
38540 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
38550 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
38560 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
38570 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
38580 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
38590 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
385a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
385b0 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
385c0 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
385d0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
385e0 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
385f0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
38600 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
38610 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
38620 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
38630 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
38640 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
38650 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
38660 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
38670 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
38680 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
38690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
386a0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
386b0 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
386c0 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
386d0 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
386e0 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
386f0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
38700 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
38710 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
38720 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
38730 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
38740 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
38750 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
38760 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
38770 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
38780 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
38790 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.**